Otk File Selection Browser Widget -

OtkWidget Otk_Browse_Files( 
				char *prompt, 
				int maxlength, 
				char *directory, 
				char *filetype_filter, 
				char *filename, 
				void (*callback)(char *fname)
			  )

This is a higher level convenience widget that is useful for helping the user find files to open, 
save-as, import, or etc..  You can indicate the intended operation to the user through the prompt
argument.  The Otk_Browse_Files widget allows navigation of the file system by showing the
files in the directory, and by going up and down into other directories.  It allows filtering the
displayed files.  Defaults can be supplied for the file name, directory, and filter (wildcards), 
which the user can also change.  The Otk_Browse_Files routine will call the user-supplied
call-back routine when a file is selected.  It passes the selected file's name as a character
string into the call-back function, where you can open the file for reading/writing, or whatever.  

Where:
 prompt - Input (can be constant literal string).  The "title" string or purpose
	 of the browser window.  For example:  "Open", "Save-As", "Import", etc..
 maxlength - The minimum array size of the next three character string parameters, 
	(directory, wildcard, filename).  If any strings to be returned are longer than or equal
	to maxlength, then the returned string is truncated to maxlength-1 characters for safety.
 directory - Input/Output.  Must point to an allocated[*] character string array variable
	of size maxlength or greater.  This specifies the starting directory for browsing.
	Often set to "." (local directory) initially.  If user browses to other directories,
	then last visited directory path is copied to this string.  Path may be relative or absolute.
 filetype_filter - Input/Output.  Must point to an allocated[*] character string array
	variable of size maxlength or greater.  This specifies the type of files to filter and
	list, much like file-wildcards, such as *.doc .  For example, "*.txt *.dat", 
	or for everything "*".  If the user changes the file-type setting, the new setting is
	returned in this string.
 filename - Input/Output.  Must point to an allocated[*] character string array variable of
        size maxlength or greater.  This specifies any initial file-name to place in the
	file-name box, if any.  Often, an empty file-name string is passed in.
	The selected file name is copied into this string.  The whole purpose of this
	widget is to select the file-name, so this is the primary output of the routine.
	At most maxlength-1 characters will be copied into the file-name array.
 callback - The user's callback function.  Function will called when file is selected.
	The selected file is passed as the argument.

[* Or permanently (static) declared character string array.]

 Example Usage:  You would call browsetest to use it.

	char directory[999]=".", wildcards[999]="", filename[999]="";

	void my_file_answer( char *filename )
	{  
	 printf("Browsing returned file-name: '%s'\n", filename );
	}

	void browsetest()
	{
	 Otk_Browse_Files( "File to Open:", 999, directory, wildcards, filename, my_file_answer );
	}

For complete example, see: File Browser Example.

Additional File-Browser Functions:

You can provide a pull-down menu to the right of the file-name entry, for the purpose of
suggesting alternate, or recently visited, directory(s) or files, with the following
function:

  Otk_fb_add_optional_dirfile( char *dir_or_file );  

Example:
  Otk_fb_add_optional_dirfile( "/home/bart/soup_recipes" );
  Otk_fb_add_optional_dirfile( "/home/bart/cake_recipes" );

All entries made by this function will be available on all future calls to the
file-browser, until cleared by the following function:

  Otk_fb_clear_optional_dirfiles();


Normally, all files are displayed in the file-browser.  However, if you wish to
prevent so-called hidden-files (files beginning with a dot) from shwowing,
call the showdotfiles function with zero before calling the file-browser:

  Otk_fbrowse_showdotfiles( int state );

Setting it to false (0), prevents (.dot) files from display.  By default. the state is
initially true (1).  Once the state is set, it remains in effect, unless changed.

Sometimes your application needs to locate a directory; not a particular file.
In this case, is the Otk_Browse_Dirs function, instead of Otk_Browse_Files.

   Otk_Browse_Dirs( char *prompt, int maxlength, char *directory, char *wildcards, 
                            char *dirname, void (*callback)(char *fdname) );


This function returns only directories. Users can navigate directories by double-clicking them.
The final directory is selected by clicking the OK button.


The file and directory-browser gadgets attempt to display themselves at a reasonable size and
aspect ratio, depending on the application window's size.  For various reasons, you may wish
to have the browser be a different size, aspect ratio, or screen position.  You can control
these things with the Otk_fbrowse_size_hint function.

   Otk_fbrowse_size_hint( float width, float height, float horiz_center_offset,  float vert_center_offset );


The coordinates are all in percent of the outer window.

Back to main page