From 9ca9171e7a35f4a2b3b6c8b52bdc966218b8137f Mon Sep 17 00:00:00 2001 From: Michael R Sweet Date: Thu, 18 Apr 2002 19:10:56 +0000 Subject: Fl_Text_Buffer docos. Reformat function reference (still need to add rest of drawing functions...) git-svn-id: file:///fltk/svn/fltk/branches/branch-1.1@2096 ea41ed52-d2ee-0310-a9c1-e6b18d33e121 --- documentation/functions.html | 1003 ++++++++++++++++++++++++++++++++++-------- 1 file changed, 825 insertions(+), 178 deletions(-) (limited to 'documentation/functions.html') diff --git a/documentation/functions.html b/documentation/functions.html index e999f4214..6dd68e13e 100644 --- a/documentation/functions.html +++ b/documentation/functions.html @@ -1,14 +1,194 @@ - + + -

B - Function Reference

+

B - Function Reference

-This appendix describes all of the fl_ functions. For a +

This appendix describes all of the fl_ functions. For a description of the FLTK classes, see Appendix A. -

Functions

+

Function List by Name

-

void fl_beep(int type = FL_BEEP_DEFAULT)

+ + +

Function List by Category

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

fl_alert

+ +
+ +

Include Files

+ + + +

Prototype

+ + + +

Description

+ +

Same as fl_message() except for the "!" symbol. + +

The fl_alert window + + + +

fl_ask

+ +
+ +

Include Files

+ + + +

Prototype

+ + + +

Description

+ +

Displays a printf-style message in a pop-up box with an +"Yes" and "No" button and waits for the user +to hit a button. The return value is 1 if the user hits Yes, 0 +if they pick No. The enter key is a shortcut for Yes and ESC is +a shortcut for No. + +

The fl_ask window. + + + +

fl_beep

+ +
+ +

Include Files

+ + + +

Prototype

+ + + +

Description

Sounds an audible notification; the default type argument sounds a simple "beep" sound. Other values for type may use @@ -35,233 +215,700 @@ a system or user-defined sound file: -

int fl_color_chooser(const char -*title, double &r, double &g, double &b) -
int fl_color_chooser(const char *title, uchar &r, uchar &g, uchar &b)

+ + +

fl_choice

+ +
+ +

Include Files

+ + + +

Prototype

+ + + +

Description

+ +

Shows the message with three buttons below it marked with the +strings b0, b1, and b2. Returns 0, +1, or 2 depending on which button is hit. ESC is a shortcut for +button 0 and the enter key is a shortcut for button 1. Notice +the buttons are positioned "backwards". You can hide +buttons by passing NULL as their labels. + +

The fl_choice window. + + + +

fl_color_chooser

+ +
+ +

Include Files

+ + + +

Prototype

+ + + +

Description

The double version takes RGB values in the range 0.0 to 1.0. The uchar version takes RGB values in the range 0 to 255. The title argument specifies the label (title) for the window. -

The fl_color_chooser dialog. +

The fl_color_chooser dialog.

-

fl_color_chooser() pops up a window to let the user pick an -arbitrary RGB color. They can pick the hue and saturation in the "hue -box" on the left (hold down CTRL to just change the saturation), and -the brighness using the vertical slider. Or they can type the 8-bit -numbers into the RGB -Fl_Value_Input fields, or drag the mouse across them to adjust -them. The pull-down menu lets the user set the input fields to show -RGB, HSV, or 8-bit RGB (0 to 255). +

fl_color_chooser() pops up a window to let the user +pick an arbitrary RGB color. They can pick the hue and +saturation in the "hue box" on the left (hold down +CTRL to just change the saturation), and the brighness using the +vertical slider. Or they can type the 8-bit numbers into the +RGB +Fl_Value_Input fields, or drag the mouse across them to +adjust them. The pull-down menu lets the user set the input +fields to show RGB, HSV, or 8-bit RGB (0 to 255). -

This returns non-zero if the user picks ok, and updates the RGB -values. If the user picks cancel or closes the window this returns -zero and leaves RGB unchanged. +

This returns non-zero if the user picks ok, and updates the +RGB values. If the user picks cancel or closes the window this +returns zero and leaves RGB unchanged. -

If you use the color chooser on an 8-bit screen, it will allocate -all the available colors, leaving you no space to exactly represent the -color the user picks! You can however use -fl_rectf() to fill a region with a simulated color using -dithering. +

If you use the color chooser on an 8-bit screen, it will +allocate all the available colors, leaving you no space to +exactly represent the color the user picks! You can however use + fl_rectf() to fill a +region with a simulated color using dithering. -

int fl_show_colormap(int oldcol)

-fl_show_colormap() pops up a panel of the 256 colors you can -access with fl_color() and lets the user -pick one of them. It returns the new color index, or the old one if -the user types ESC or clicks outside the window. -

The fl_show_colormap dialog + +

fl_color_cube

-

void fl_message(const char *, ...)

+
-Displays a printf-style message in a pop-up box with an "OK" button, -waits for the user to hit the button. The message will wrap to fit the -window, or may be many lines by putting \n characters into it. -The enter key is a shortcut for the OK button. -

The fl_message window. +

Include File

-

void fl_alert(const char *, ...)

+ -Same as fl_message() except for the "!" symbol. -

The fl_alert window +

Prototype

+ + -

int fl_ask(const char *, ...)

+

Description

-Displays a printf-style message in a pop-up box with an -"Yes" and "No" button and waits for the user to -hit a button. The return value is 1 if the user hits Yes, 0 if they -pick No. The enter key is a shortcut for Yes and ESC is a shortcut -for No. +

Returns a color out of the color cube. r must be in +the range 0 to FL_NUM_RED (5) minus 1. g must be in the +range 0 to FL_NUM_GREEN (8) minus 1. b must be in the +range 0 to FL_NUM_BLUE (5) minus 1. -

The fl_ask window. +

To get the closest color to a 8-bit set of R,G,B values use: -

int fl_choice(const char *q, const char *b0, -const char *b1, const char *b2, ...)

+ -Shows the message with three buttons below it marked with the strings - b0, b1, and b2. Returns 0, 1, or 2 -depending on which button is hit. ESC is a shortcut for button 0 and -the enter key is a shortcut for button 1. Notice the buttons are -positioned "backwards" You can hide buttons by passing -NULL as their labels. -

The fl_choice window. + +

fl_file_chooser

-

const char *fl_input(const char *label, const char -*deflt = 0, ...)

+
-Pops up a window displaying a string, lets the user edit it, and -return the new value. The cancel button returns NULL. The -returned pointer is only valid until the next time fl_input() -is called. Due to back-compatability, the arguments to any printf -commands in the label are after the default value. +

Include Files

-

The fl_input window. +

-

const char *fl_password(const char *label, -const char *deflt = 0, ...)

+

Prototype

-Same as fl_input() except an Fl_Secret_Input field is used. + -

The fl_password window. +

Description

-

void fl_message_font(Fl_Font fontid, uchar -size)

+

FLTK provides a "tab completion" file chooser that +makes it easy to choose files from large directories. This file +chooser has several unique features, the major one being that +the Tab key completes filenames like it does in Emacs or tcsh, +and the list always shows all possible completions. -Change the font and font size used for the messages in all the popups. +

The fl_file_chooser window. -

Fl_Widget *fl_message_icon()

+

fl_file_chooser() pops up the file chooser, waits +for the user to pick a file or Cancel, and then returns a +pointer to that filename or NULL if Cancel is chosen. -Returns a pointer to the box at the left edge of all the popups. You -can alter the font, color, or label (including making it a Pixmap), -before calling the functions. +

message is a string used to title the window. -

char *fl_file_chooser(const char * message, -const char *pattern, const char *fname)

+

pattern is used to limit the files listed in a +directory to those matching the pattern. This matching is done +by fl_filename_match(). Use +NULL to show all files. -FLTK provides a "tab completion" file chooser that makes it easy to -choose files from large directories. This file chooser has several -unique features, the major one being that the Tab key completes -filenames like it does in Emacs or tcsh, and the list always shows all -possible completions. +

fname is a default filename to fill in the chooser +with. If this is NULL then the last filename that was +choosen is used (unless that had a different pattern, in which +case just the last directory with no name is used). The first +time the file chooser is called this defaults to a blank string. -

The fl_file_chooser window. +

The returned value points at a static buffer that is only +good until the next time fl_file_chooser() is called. -fl_file_chooser() pops up the file chooser, waits for the user -to pick a file or Cancel, and then returns a pointer to that filename -or NULL if Cancel is chosen. -

message is a string used to title the window. + +

fl_file_chooser_callback

+ +
+ +

Include Files

+ + + +

Prototype

+ + + +

Description

+ +

Sets a function that is called every time the user clicks a +file in the currently popped-up file chooser. This could be used +to preview the contents of the file. It has to be reasonably +fast, and cannot create FLTK windows. + + + +

fl_filename_absolute

+ +
+ +

Include Files

+ + + +

Prototype

+ + + +

Description

+ +

Converts a relative pathname to an absolute pathname. If +from does not start with a slash, the current working +directory is prepended to from with any occurances of +. and x/.. deleted from the result. The +absolute pathname is copied to to; from and +to may point to the same buffer. +fl_filename_absolute returns non-zero if any changes +were made. + +

The first form accepts a maximum length (tolen) for +the destination buffer, while the second form assumes that the +destination buffer is at least FL_PATH_MAX characters +in length. + + + +

fl_filename_expand

+ +
+ +

Include Files

+ + + +

Prototype

+ + + +

Description

+ +

This function replaces environment variables and home +directories with the corresponding strings. Any occurrence of +$X is replaced by getenv("X"); if +$X is not defined in the environment, the occurrence is +not replaced. Any occurence of ~X is replaced by user +X's home directory; if user X does not exist, +the occurrence is not replaced. Any resulting double slashes +cause everything before the second slash to be deleted. + +

The result is copied to to, and from and +to may point to the same buffer. +fl_filename_expand() returns non-zero if any changes +were made. + +

The first form accepts a maximum length (tolen) for +the destination buffer, while the second form assumes that the +destination buffer is at least FL_PATH_MAX characters +in length. + + + +

fl_filename_ext

+ +
+ +

Include Files

+ + + +

Prototype

+ + + +

Description

+ +

Returns a pointer to the last period in +fl_filename_name(f), or a pointer to the trailing +nul if none is found. -

pattern is used to limit the files listed in a directory to -those matching the pattern. This matching is done by -fl_filename_match(). Use NULL to show all files. - -

fname is a default filename to fill in the chooser with. -If this is NULL then the last filename that was choosen is -used (unless that had a different pattern, in which case just the last -directory with no name is used). The first time the file chooser is -called this defaults to a blank string. - -

The returned value points at a static buffer that is only good until -the next time fl_file_chooser() is called. - -

void fl_file_chooser_callback(void -(*cb)(const char *))

- -Set a function that is called every time the user clicks a file in the -currently popped-up file chooser. This could be used to preview the -contents of the file. It has to be reasonably fast, and cannot create -FLTK windows. - -

int fl_filename_list(const char *d, dirent -***list)

- -This is a portable and const-correct wrapper for the -fl_scandir function. d is the name of a directory -(it does not matter if it has a trailing slash or not). For each file -in that directory a "dirent" structure is created. The only -portable thing about a dirent is that dirent.d_name is the -nul-terminated file name. An array of pointers to these dirents is -created and a pointer to the array is returned in *list. The -number of entries is given as a return value. If there is an error -reading the directory a number less than zero is returned, and -errno has the reason (errno does not work under -WIN32). The files are sorted in "alphanumeric" order, where -an attempt is made to put unpadded numbers in consecutive order. -

You can free the returned list of files with the following code: + +

fl_filename_isdir

- +
-

int fl_filename_isdir(const char *f)

+

Include Files

-Returns non-zero if the file exists and is a directory. + -

const char *fl_filename_name(const char *f)

+

Prototype

-Returns a pointer to the character after the last slash, or to the -start of the filename if there is none. + -

const char *fl_filename_ext(const char *f)

+

Description

-Returns a pointer to the last period in fl_filename_name(f), or -a pointer to the trailing nul if none. +

Returns non-zero if the file exists and is a directory. -

char *fl_filename_setext(char *f, const char -*ext)

-Does strcpy(fl_filename_ext(f), ext ? ext : ""). Returns a -pointer to f. + +

fl_filename_list

-

int fl_filename_expand(char *out, const char -*in)

+
-Splits in at each slash character. Replaces any occurrance -of $X with getenv("X") (leaving it as -$X if the environment variable does not exist). Replaces any -occurances of ~X with user X's home directory -(leaving it as ~X if the user does not exist). Any resulting -double slashes cause everything before the second slash to be deleted. -Copies the result to out (in and out may -be the same buffer). Returns non-zero if any changes were made. In -true retro programming style, it is up to you to provide a buffer big -enough for the result. 1024 characters should be enough. +

Include Files

-

int fl_filename_absolute(char *out, const -char *in)

+ -If in does not start with a slash, this prepends the current -working directory to in and then deletes any occurances of -. and x/.. from the result, which it copies to out (in -and out may be the same buffer). Returns non-zero if any -changes were made. In true retro programming style, it is up to you -to provide a buffer big enough for the result. 1024 characters should -be enough. +

Prototype

-

int fl_filename_match(const char *f, const char -*pattern)

+ -Returns true if f matches pattern. The following -syntax is used by pattern: +

Description

+ +

This is a portable and const-correct wrapper for the +scandir() function. d is the name of a +directory; it does not matter if it has a trailing slash or not. +For each file in that directory a "dirent" structure +is created. The only portable thing about a dirent is that +dirent.d_name is the nul-terminated file name. +An array of pointers to these dirent's is created and a +pointer to the array is returned in *list. The number +of entries is given as a return value. If there is an error +reading the directory a number less than zero is returned, and +errno has the reason; errno does not work +under WIN32. The files are sorted in "alphanumeric" +order, where an attempt is made to put unpadded numbers in +consecutive order. + +

You can free the returned list of files with the following +code: + +

+ + + +

fl_filename_match

+ +
+ +

Include Files

+ + + +

Prototype

+ + + +

Description

+ +

Returns non-zero if f matches pattern. The +following syntax is used by pattern:

- - + + +

fl_filename_name

+ +
+ +

Include Files

+ + + +

Prototype

+ + + +

Description

+ +

Returns a pointer to the character after the last slash, or +to the start of the filename if there is none. + + + +

fl_filename_relative

+ +
+ +

Include Files

+ + + +

Prototype

+ + + +

Description

+ +

Converts an absolute pathname to an relative pathname. The +relative pathname is copied to to; from and +to may point to the same buffer. +fl_filename_relative returns non-zero if any changes +were made. + +

The first form accepts a maximum length (tolen) for +the destination buffer, while the second form assumes that the +destination buffer is at least FL_PATH_MAX characters +in length. + + + +

fl_filename_setext

+ +
+ +

Include Files

+ + + +

Prototype

+ + + +

Description

+ +

Replaces the extension in to with the extension in +ext. Returns a pointer to to. + +

The first form accepts a maximum length (tolen) for +the destination buffer, while the second form assumes that the +destination buffer is at least FL_PATH_MAX characters +in length. + + + +

fl_gray_ramp

+ +
+ +

Include File

+ + + +

Prototype

+ + + +

Description

+ +

Returns a gray color value from black (i == 0) to +white (i == FL_NUM_GRAY - 1). FL_NUM_GRAY is +defined to be 24 in the current FLTK release. To get the closest +FLTK gray value to an 8-bit grayscale color 'I' use: + +

+ + + +

fl_input

+ +
+ +

Include Files

+ + + +

Prototype

+ + + +

Description

+ +

Pops up a window displaying a string, lets the user edit it, +and return the new value. The cancel button returns +NULL. The returned pointer is only valid until the +next time fl_input() is called. Due to +back-compatability, the arguments to any printf commands in the +label are after the default value. + +

The fl_input window. + + + +

fl_message

+ +
+ +

Include Files

+ + + +

Prototype

+ + + +

Description

+ +

Displays a printf-style message in a pop-up box with an +"OK" button, waits for the user to hit the button. +The message will wrap to fit the window, or may be many lines by +putting \n characters into it. The enter key is a +shortcut for the OK button. + +

The fl_message window. + + + +

fl_message_font

+ +
+ +

Include Files

+ + + +

Prototype

+ + + +

Description

+ +

Changes the font and font size used for the messages in all +the popups. + + + +

fl_message_icon

+ +
+ +

Include Files

+ + + +

Prototype

+ + + +

Description

+ +

Returns a pointer to the box at the left edge of all the +popups. You can alter the font, color, label, or image before +calling the functions. + + + +

fl_password

+ +
+ +

Include Files

+ + + +

Prototype

+ + + +

Description

+ +

Same as fl_input(), except an Fl_Secret_Input field is +used. + + + +

fl_rgb_color

+ +
+ +

Include File

+ + + +

Prototype

+ + + +

Description

+ +

Returns the 24-bit RGB color value for the specified 8-bit +RGB or grayscale values. + + + +

fl_show_colormap

+ +
+ +

Include Files

+ + + +

Prototype

+ + + +

Description

+ +

fl_show_colormap() pops up a panel of the 256 colors +you can access with fl_color() and lets +the user pick one of them. It returns the new color index, or +the old one if the user types ESC or clicks outside the window. + +

The fl_show_colormap dialog + + + + -- cgit v1.2.3