From 09daf20b81cdae78772f07c0af22a571d7cc73eb Mon Sep 17 00:00:00 2001 From: Michael R Sweet Date: Thu, 29 Nov 2001 19:24:00 +0000 Subject: Documentation updates galore (up to chapter 7, still need to do chapter 8 and 9, tweek the appendices, and recapture the screenshots...) git-svn-id: file:///fltk/svn/fltk/branches/branch-1.1@1786 ea41ed52-d2ee-0310-a9c1-e6b18d33e121 --- documentation/osissues.html | 318 ++++++++++++++++++++++---------------------- 1 file changed, 159 insertions(+), 159 deletions(-) (limited to 'documentation/osissues.html') diff --git a/documentation/osissues.html b/documentation/osissues.html index 4eede262b..c52c1d615 100644 --- a/documentation/osissues.html +++ b/documentation/osissues.html @@ -1,56 +1,56 @@

F - Operating System Issues

- This appendix describes the X and WIN32 specific interfaces in FLTK. + This appendix describes the X and WIN32 specific interfaces in FLTK.

X-Specific Interface

- On X you can include this file to access FLTK's X-specific functions. - Be warned that some of the structures and calls in it are subject to -change in future version of FLTK. Try to avoid doing this so your code -is portable. + On X you can include this file to access FLTK's X-specific functions. + Be warned that some of the structures and calls in it are subject to +change in future version of FLTK. Try to avoid doing this so your code +is portable.

Handling Other X Events

void Fl::add_handler(int (*f)(int))

- Installs a function to parse unrecognized events. If FLTK cannot -figure out what to do with an event, it calls each of these functions -(most recent first) until one of them returns non-zero. If none of -them returns non-zero then the event is ignored. -

FLTK calls this for any X events it does not recognize, or X events -with a window id that FLTK does not recognize. You can look at the X + Installs a function to parse unrecognized events. If FLTK cannot +figure out what to do with an event, it calls each of these functions +(most recent first) until one of them returns non-zero. If none of +them returns non-zero then the event is ignored. +

FLTK calls this for any X events it does not recognize, or X events +with a window id that FLTK does not recognize. You can look at the X event with the fl_xevent variable.

-

The argument is zero for unrecognized X events. These handlers are -also called for global shortcuts and some other events that the widget -they were passed to did not handle. In this case the argument is +

The argument is zero for unrecognized X events. These handlers are +also called for global shortcuts and some other events that the widget +they were passed to did not handle. In this case the argument is non-zero (for example FL_SHORTCUT).

extern XEvent *fl_xvent

- The most recent X event. + The most recent X event.

extern ulong fl_event_time

- This is the time stamp from the most recent X event that reported it -(not all do). Many X calls (like cut and paste) need this value. + This is the time stamp from the most recent X event that reported it +(not all do). Many X calls (like cut and paste) need this value.

Window fl_xid(const Fl_Window *)

- Returns the XID for a window, or zero if not shown(). + Returns the XID for a window, or zero if not shown().

Fl_Window *fl_find(ulong xid)

Returns the Fl_Window that corresponds to the given XID, or -NULL if not found. This uses a cache so it is slightly faster -than iterating through the windows yourself. +NULL if not found. This uses a cache so it is slightly faster +than iterating through the windows yourself.

int fl_handle(const XEvent &)

- This call allows you to supply the X events to FLTK, which may allow -FLTK to cooperate with another toolkit or library. The return value is -true if FLTK understood the event (if the window does not belong to -FLTK and the add_handler() functions all ignore it this -returns false). + This call allows you to supply the X events to FLTK, which may allow +FLTK to cooperate with another toolkit or library. The return value is +true if FLTK understood the event (if the window does not belong to +FLTK and the add_handler() functions all ignore it this +returns false).

Besides feeding events your code should call Fl::flush() periodically so that FLTK redraws its windows.

-

This function will call the callback functions. It will not return -until they complete. In particular if a callback pops up a modal -window (by calling fl_ask(), +

This function will call the callback functions. It will not return +until they complete. In particular if a callback pops up a modal +window (by calling fl_ask(), for instance) it will not return until the modal function returns.

Drawing using Xlib

The following global variables are set before Fl_Widget::draw() is called, or by -Fl_Window::make_current(): +Fl_Window::make_current(): - You must use them to produce Xlib calls. Don't attempt to change -them. A typical X drawing call is written like this: + You must use them to produce Xlib calls. Don't attempt to change +them. A typical X drawing call is written like this: - Other information such as the position or size of the X window can be + Other information such as the position or size of the X window can be found by looking at Fl_Window::current(), which returns a pointer to the -Fl_Window being drawn. +Fl_Window being drawn.

unsigned long fl_xpixel(Fl_Color i)
unsigned long fl_xpixel(uchar r, uchar g, uchar b)

- Returns the X pixel number used to draw the given FLTK color index or + Returns the X pixel number used to draw the given FLTK color index or RGB color. This is the X pixel that fl_color() - would use. + would use.

extern XFontStruct *fl_xfont

Points at the font selected by the most recent fl_font(). This is not necessarily the current font of fl_gc, which is not set until fl_draw() - is called. + is called.

Changing the Display, Screen, or X Visual

- FLTK uses only a single display, screen, X visual, and X colormap. -This greatly simplifies its internal structure and makes it much -smaller and faster. You can change which it uses by setting global -variables before the first Fl_Window::show() is called. + FLTK uses only a single display, screen, X visual, and X colormap. +This greatly simplifies its internal structure and makes it much +smaller and faster. You can change which it uses by setting global +variables before the first Fl_Window::show() is called. You may also want to call Fl::visual() -, which is a portable interface to get a full color and/or double -buffered visual. +, which is a portable interface to get a full color and/or double +buffered visual.

int Fl::display(const char *)

Set which X display to use. This actually does -putenv("DISPLAY=...") so that child programs will display on the -same screen if called with exec(). This must be done before -the display is opened. This call is provided under WIN32 but it has no -effect. +putenv("DISPLAY=...") so that child programs will display on the +same screen if called with exec(). This must be done before +the display is opened. This call is provided under WIN32 but it has no +effect.

extern Display *fl_display

- The open X display. This is needed as an argument to most Xlib calls. -Don't attempt to change it! This is NULL before the display -is opened. + The open X display. This is needed as an argument to most Xlib calls. +Don't attempt to change it! This is NULL before the display +is opened.

void fl_open_display()

- Opens the display. Does nothing if it is already open. This will -make sure fl_display is non-zero. You should call this if you -wish to do X calls and there is a chance that your code will be called -before the first show() of a window. -

This may call Fl::abort() if there is an error opening the + Opens the display. Does nothing if it is already open. This will +make sure fl_display is non-zero. You should call this if you +wish to do X calls and there is a chance that your code will be called +before the first show() of a window. +

This may call Fl::abort() if there is an error opening the display.

void fl_close_display()

- This closes the X connection. You do not need to call this to -exit, and in fact it is faster to not do so! It may be useful to call -this if you want your program to continue without the X connection. You -cannot open the display again, and probably cannot call any FLTK -functions. + This closes the X connection. You do not need to call this to +exit, and in fact it is faster to not do so! It may be useful to call +this if you want your program to continue without the X connection. You +cannot open the display again, and probably cannot call any FLTK +functions.

extern int fl_screen

Which screen number to use. This is set by fl_open_display() - to the default screen. You can change it by setting this to a -different value immediately afterwards. It can also be set by changing -the last number in the Fl::display() string to "host:0,#". + to the default screen. You can change it by setting this to a +different value immediately afterwards. It can also be set by changing +the last number in the Fl::display() string to "host:0,#".

extern XVisualInfo *fl_visual
extern Colormap fl_colormap

- The visual and colormap that FLTK will use for all windows. These are -set by fl_open_display() to the default visual and colormap. - You can change them before calling show() on the first -window. Typical code for changing the default visual is: + The visual and colormap that FLTK will use for all windows. These are +set by fl_open_display() to the default visual and colormap. + You can change them before calling show() on the first +window. Typical code for changing the default visual is:

Using a Subclass of Fl_Window for Special X Stuff

- FLTK can manage an X window on a different screen, visual and/or -colormap, you just can't use FLTK's drawing routines to draw into it. -But you can write your own draw() method that uses Xlib -(and/or OpenGL) calls only. -

FLTK can also manage XID's provided by other libraries or programs, + FLTK can manage an X window on a different screen, visual and/or +colormap, you just can't use FLTK's drawing routines to draw into it. +But you can write your own draw() method that uses Xlib +(and/or OpenGL) calls only. +

FLTK can also manage XID's provided by other libraries or programs, and call those libraries when the window needs to be redrawn.

To do this, you need to make a subclass of Fl_Window and override some of these virtual functions:

virtual void Fl_Window::show()

- If the window is already shown() this must cause it to be -raised, this can usually be done by calling Fl_Window::show(). + If the window is already shown() this must cause it to be +raised, this can usually be done by calling Fl_Window::show(). If not shown() your implementation must call either -Fl_X::set_xid() or Fl_X::make_xid(). +Fl_X::set_xid() or Fl_X::make_xid().

An example:

Fl_X *Fl_X::set_xid(Fl_Window *, Window xid)

- Allocate a hidden structure called an Fl_X, put the XID into + Allocate a hidden structure called an Fl_X, put the XID into it, and set a pointer to it from the Fl_Window. This causes -Fl_Window::shown() to return true. -

void Fl_X::make_xid(Fl_Window *, XVisualInfo *= fl_visual, Colormap +Fl_Window::shown() to return true. +

void Fl_X::make_xid(Fl_Window *, XVisualInfo *= fl_visual, Colormap = fl_colormap)

- This static method does the most onerous parts of creating an X -window, including setting the label, resize limitations, etc. It then -does Fl_X::set_xid() with this new window and maps the window. + This static method does the most onerous parts of creating an X +window, including setting the label, resize limitations, etc. It then +does Fl_X::set_xid() with this new window and maps the window.

virtual void Fl_Window::flush()

- This virtual function is called by Fl::flush() to update the -window. For FLTK's own windows it does this by setting the global + This virtual function is called by Fl::flush() to update the +window. For FLTK's own windows it does this by setting the global variables fl_window and fl_gc and then calling the -draw() method. For your own windows you might just want to put -all the drawing code in here. -

The X region that is a combination of all damage() calls +draw() method. For your own windows you might just want to put +all the drawing code in here. +

The X region that is a combination of all damage() calls done so far is in Fl_X::i(this)->region. If NULL then you should redraw the entire window. The undocumented function -fl_clip_region(XRegion) will initialize the FLTK clip stack with a +fl_clip_region(XRegion) will initialize the FLTK clip stack with a region or NULL for no clipping. You must set region to -NULL afterwards as fl_clip_region() now owns it and will +NULL afterwards as fl_clip_region() now owns it and will delete it when done.

-

If damage() FL_DAMAGE_EXPOSE then only X expose events have -happened. This may be useful if you have an undamaged image (such as a +

If damage() FL_DAMAGE_EXPOSE then only X expose events have +happened. This may be useful if you have an undamaged image (such as a backing buffer) around.

Here is a sample where an undamaged image is kept somewhere:

virtual void Fl_Window::hide()

- Destroy the window server copy of the window. Usually you will -destroy contexts, pixmaps, or other resources used by the window, and -then call Fl_Window::hide() to get rid of the main window -identified by xid(). If you override this, you must also -override the destructor as shown: + Destroy the window server copy of the window. Usually you will +destroy contexts, pixmaps, or other resources used by the window, and +then call Fl_Window::hide() to get rid of the main window +identified by xid(). If you override this, you must also +override the destructor as shown: