X11FileSelectDialog (Ctalk)

A X11FileSelectDialog object displays a dialog box with a list of files in the current directory, a preselected target directory, or a subdirectory that a user selects from the current directory’s entries.

The class allows users to select multiple entries by holding either the Shift or Ctrl keys while selecting items. The class provides a number of methods to retrieve the number of items that the user selects, the items’ text, and text for a new file that the user enters, if any. These methods are described below. See Retrieving-Selection-Information.

The X11FileSelectDialog class can also display a text entry box (from X11TextEntryPane class) where users can enter new file names.


/* -*-c-*- */

/* 
 *   fileselectbox.ca, a X11FileSelectDialog demonstration. 
 *
 *     To build:
 * 
 *       ctcc -x fileselectbox.ca -o fileselectbox
 *
 *     You can optionally buidl the dialog with a X11TextEntryPane
 *     so you can enter filenames by typing.  For a full description
 *     of the X11FileSelectDialog class, refer to the Ctalk Language
 *     Reference.
 */

/*
 *  Uncomment the following #define if you want to build the dialog
 *  with a X11TextEntryPane for creating new file paths.
 */
/* #define FILENAME_ENTRY_BOX */

#include <ctalk/ctalkdefs.h>

int main (void) {
  X11Pane new mainWindow;
  X11PaneDispatcher new dispatcher;
  X11ButtonPane new button;
  X11LabelPane new label;
  X11FileSelectDialog new fileSelect;
  InputEvent new e;
  Integer new i;
  List new itemTextOut, itemNOut;
  String new itemText, itemN;

  label textColor = "white";
  label canFocus = false;
  label borderWidth = 0;

  label ftFontVar initFontLib;
  label ftFontVar notifyLevel XFT_NOTIFY_NONE;

  mainWindow backgroundColor = "blue";
  label resources replaceAt "backgroundColor", "blue";
  button resources replaceAt "backgroundColor", "blue";
  fileSelect resources replaceAt "backgroundColor", "blue";
  
  mainWindow initialize 255, 245;
  mainWindow inputStream eventMask = 
    EXPOSE|ENTERWINDOWNOTIFY|LEAVEWINDOWNOTIFY|BUTTONPRESS|BUTTONRELEASE|KEYPRESS|KEYRELEASE|WINDELETE|MOVENOTIFY|MOTIONNOTIFY;

  dispatcher attachTo mainWindow;
  label attachTo dispatcher, "177x60+c+35";
  button attachTo dispatcher, "110x105+c+100";
  fileSelect attachTo dispatcher, "300x400";

  mainWindow map;
  mainWindow raiseWindow;

  mainWindow openEventStream;

#ifdef FILENAME_ENTRY_BOX
  fileSelect resources replaceAt "useEntryBox", TRUE;
#endif  

  mainWindow setWMTitle "X11FileSelectDialog Demo";

  label multiLine "X11FileSelectDialog\nDemo";
  label resources replaceAt "textColor", "lightgray";
  label resources replaceAt "foregroundColor", "blue";
  label resources replaceAt "borderColor", "blue";

  button label multiLine "Open\nFile Select\nDialog";

  button label resources replaceAt "highlightForegroundColor", "gray80";

  /* The program uses the "replaceAt" method because the key/value
     entry for "backgroundColor" the X11MessageBoxPane : new method
     has alread created an entry for backgroundColor. */
  fileSelect resources replaceAt "backgroundColor", "blue";
  fileSelect resources replaceAt "foregroundColor", "blue";
  fileSelect resources replaceAt "messageColor", "white";
  fileSelect resources replaceAt "messageText",
    	       "Directory:\n";

  button draw;
  button refresh;
  label draw;
  label refresh;

  while (TRUE) {
    mainWindow inputStream queueInput;
    if (mainWindow inputStream eventPending) {
      e become mainWindow inputStream inputQueue unshift;

      mainWindow subPaneNotify e;

      switch (e eventClass value)
	{
	case EXPOSE:
	  button subPaneExpose (button, e);
	  label subPaneExpose (label, e);
	  break;
	case BUTTONRELEASE:
	  fileSelect showManaged button;
	  if (fileSelect buttonClick == FILESELECT_LBUTTON) {
	    printf ("\"%s,\" clicked.\n", fileSelect buttonText);
	    /* 
	       The button's click should be cleared, because in this
	       program, the dialog can be re-opened here (i.e., not 
	       reinstantiated with the "new" method). 

	       The, "buttonText," method is equivalent, in this clause, 
	       to, "fileSelect lbutton text."

	       The FILESELECT_LBUTTON #define and the other button
	       definitions, are in ctalkdefs.h.
	    */
	    fileSelect lbutton clearClick;
	  } else if (fileSelect entryLength > 0) {
	    printf ("%s\n", fileSelect pathEntry);
	  } else if (fileSelect nItemsSelected > 1) {
	    i = 0;
	    fileSelect selectedItems itemTextOut;
	    fileSelect selectedItemsN itemNOut;
	    itemNOut map {
	      itemN = self;
	      /* This is a convenient way to retrieve
		 the i'th item in the itemTextOut list. */
	      itemText = *(itemTextOut + i);
	      printf ("%d: %s\n", itemN, itemText);
	      ++i;
	    }
	  } else {
	    printf ("%d: %s\n",
		    fileSelect selectedItemN,
		    fileSelect selectedItemText);
	  }
	  fileSelect rbutton clearClick;
	  break;
	case WINDELETE:
 	  mainWindow deleteAndClose;
	  exit (0);
	  break;
	}
    } else {
      usleep (1000);
    }
  }

}

Retrieving Selection Information

The type and number of entries that a X11FileSelectDialog can return can differ depending on whether a user selects a single directory entry, multiple directory entries, or enters a new file name.

When returning directory entries, the class returns each entry as a concatenation of the current directory plus the entry name; for example, if the current directory is ‘/home/bill’ and the user has selected the file ‘message.txt’, the dialog returns the String, ‘/home/bill/message.txt’.

In addition, the dialog can provide information about whether the user has clicked the left or right buttons, which are labeled, by default, ‘Cancel’ and Ok.

Generally, when a program displays the file select dialog, the program waits until the dialog box returns, that is, when the user presses either the ‘Cancel’ or Ok buttons. On most desktops, the user can also close the dialog using the desktop’s close window menu item. In this case, the dialog can return a value indicating that the dialog has returned without the user making a selection or cancelling the selection. These values and the method to retrieve them are described below.

Here is the section of code from the example above (without the comments) that retrieves and displays the user’s selection or selections. The file select dialog is defined in the X11FileSelectDialog object, fileSelect.


if (fileSelect buttonClick == FILESELECT_LBUTTON) {
  printf ("\"%s,\" clicked.\n", fileSelect buttonText);
  fileSelect lbutton clearClick;
} else if (fileSelect entryLength > 0) {
  printf ("%s\n", fileSelect pathEntry);
} else if (fileSelect nItemsSelected > 1) {
  i = 0;
  fileSelect selectedItems itemTextOut;
  fileSelect selectedItemsN itemNOut;
  itemNOut map {
    itemN = self;
    itemText = *(itemTextOut + i);
    printf ("%d: %s\n", itemN, itemText);
    ++i;
  }
} else {
  printf ("%d: %s\n",
          fileSelect selectedItemN,
          fileSelect selectedItemText);
}
fileSelect rbutton clearClick;

First, the application checks whether the user clicked the ‘Cancel’ button with the expresion:


if (fileSelect buttonClick == FILESELECT_LBUTTON)

In this class, buttonClick is a convenience method that checks each of the dialog’s buttons. It can return the following values.


FILESELECT_LBUTTON
FILESELECT_RBUTTON
FILESELECT_BUTTON_NONE

These values are defined in the ctalkdefs.h include file, which programs can include with a statement like this:


#include <ctalkdefs.h>

Assuming that the user has pressed the ‘Ok’ button, the program next checks if the user has entered a new file name, with the statement:


} else if (fileSelect entryLength > 0) {

The entryLength method returns ‘-1’ if the dialog doesn’t display an entry box, ‘0’ if no text is entered, or the length of the text. If the user has entered text, then the program can retrieve it with the pathEntry method, which retrieves and prints the entry with this line.


printf ("%s\n", fileSelect pathEntry);

Once again, the dialog returns a String that is the concatenation of the current directory and the filename that the user entered. To retrieve the entry box’s text alone, programs can use the textEntry method instead of pathEntry.

Finally, the program checks how many items the user selected from the directory entries. The program does this with the nItemsSelected method.


} else if (fileSelect nItemsSelected > 1) {

If nItemsSelected returns an Integer greater than one, the program can retrieve all of the entries as a list, with the selectedItems method, and their position in the list with the selectedItemsN method.


fileSelect selectedItems itemTextOut;
fileSelect selectedItemsN itemNOut;

These methods take one argument, a List object, here itemTextOut and itemNOut, to which the method adds either the list item text or ordinal position of each selected directory entry.

In the case where the user has selected only a single directory entry (i.e., nItemsSelected returns ‘1’), the program can use the selectedItemN and selectedItemText methods, as in this statement, which prints the information about a single entry.


printf ("%d: %s\n",
        fileSelect selectedItemN,
        fileSelect selectedItemText);

Resources

Further information about modifying resource entries is given in the resources instance variable section. See PaneResources.

Instance Variables

In addition to the instance variables defined in superclasses (like lbutton, rbutton, and label, which are defined in X11YesNoBoxPane class; entryPane, defined in X11TextEntryBox; and listPane, which is defined in X11ListBox class), the X11FileSelectDialog class defines the following instance variables.

X11FileSelectDialog

`X11FileSelectDialog` Class

Retrieving Selection Information

Resources

Instance Variables

Instance Methods

X11FileSelectDialog

X11FileSelectDialog Class

Retrieving Selection Information

Resources

Instance Variables

Instance Methods

`X11FileSelectDialog` Class