Difference between revisions of "Folder Selector"

Revision as of 15:09, 26 February 2011

Folder Selector

Some times you may need to allow your application user to navigate trough system folders. This class allows you to easily integrate a folder selector in your game.

Folder Selector uses DiskObject, a class that depends on <windows.h>. So, for now, there's no support for mac or linux users.

Links

• Image of the folder selector in action: preview.JPG
  
• A game currently using Folder Selector: [1]
  
• Source, project for MSVC9.0 (with SDL & OpenGL) and a live-demo: [2]
  

How to use it
To use Folder Selector in your application, you must call the method:

void show(CEGUI::Window* root);

Where CEGUI::Window* root is a pointer to the window where you want the folder selector to be opened. A file called "fs.layout" contains the current layout used by folder selector.
After that, the Folder Selector will be showed on the top and you just need to update CEGUI logic and render methods as usually. When the user selects a folder successfully or cancels the action, the folder selector hides again and your application takes the control back.
If you want to know which folder has been selected by the user, you can subscribe to the PushButton::EventClicked as follows:

// Subscribes the folder selector OK button pusehd event
    winMgr.getWindow("FolderSelector/Frame/Ok")->
      subscribeEvent(PushButton::EventClicked,
      Event::Subscriber(&handleClick));

And in your handle method, make a call to getResults() to know the selected folder:

bool handleClick(const CEGUI::EventArgs &e)
{
  using namespace CEGUI;
  WindowManager& winMgr = WindowManager::getSingleton();
  String selectedFolder(fs.getResult()); // now selectedFolder contains the full path of the directory selected.
  return 0;
}

Below you can see the FolderSelector methods and a more complete example of how to use it.

Public methods in FolderSelector.h

  /**
     @short makes the Folder selector to appear in CEGUI::Window
  */
  void show(CEGUI::Window* root);

  /**
     @short hide Folder Selector
  */
  void hide();

  /**
     @short Returns the last selected file
  */
  std::string getResult();

  /**
     @short set the current folder
  */
  void setFolder(std::string);

  /**
     @short sets the filter string. The string will be used to enable/disable OK
   button when files in the current folder matches the filter string
   (i.e., "*.jpg" string will enable OK button only when the current folder
   contains files with extension .jpg). By default is "*", showing all files.
  */
  void setFileFiler(std::string s){d_fileFilter = s;}

This is how the example looks:

#include "SDL.h"
#include "GUI_Menu.h"
#include "GUI_FolderSelector.h"
#define QUIT -1
#define MENU 0
#define FOLDER_SELECTOR 1
GUI_FolderSelector fs;
void init()
{
 // ... This is just an example, complete code in downloadable file
}
void setupCEGUI()
{
 // ... This is just an example, complete code in downloadable file
}
bool handleClick(const CEGUI::EventArgs &e)
{
 using namespace CEGUI;
 WindowManager& winMgr = WindowManager::getSingleton();
 Window* btn = static_cast<Window*>(winMgr.getWindow("Root/Play"));
     btn->setText(fs.getResult());
 return 0;
}
int main(int argc, char **argv)
{
 using namespace CEGUI;
 // init SDL/OpenGL Framework
 init();
 // init CEGUI
 setupCEGUI();
 // create main menu
 WindowManager& winMgr = WindowManager::getSingleton();
 GUI_Menu menu("menu.layout");
 //Main loop
 do
 {
   menu.injectInput();
   menu.render();
   if (menu.getState() == FOLDER_SELECTOR)
   {
     // makes appear the folder selector
     fs.show(CEGUI::System::getSingleton().getGUISheet());
     // Subscribe OK button event
     winMgr.getWindow("FolderSelector/Frame/Ok")->
       subscribeEvent(PushButton::EventClicked,
       Event::Subscriber(&handleClick));
     // back to menu (fs will auto-hide when done)
     menu.setState(MENU);
   }
   SDL_Delay(10);
 } while (menu.getState() != QUIT);
 return 0;
}

If you've got some trouble running the example just let me know at this thread: http://www.cegui.org.uk/phpBB2/viewtopic.php?f=1&t=3597&start=0
--Ivanovich78 21:47, 19 October 2008 (UTC)