From a9103714031cedb16b00cd6ce81ef93b04734f08 Mon Sep 17 00:00:00 2001 From: Michael R Sweet Date: Wed, 12 Dec 2001 15:20:27 +0000 Subject: Documentation updates, mainly to fix typos, mark constants with TT, and clean up the osissues.html file for all OS's. git-svn-id: file:///fltk/svn/fltk/branches/branch-1.1@1836 ea41ed52-d2ee-0310-a9c1-e6b18d33e121 --- documentation/osissues.html | 836 +++++++++++++++++++++++++++----------------- 1 file changed, 515 insertions(+), 321 deletions(-) (limited to 'documentation/osissues.html') diff --git a/documentation/osissues.html b/documentation/osissues.html index f67016058..e454bb5a3 100644 --- a/documentation/osissues.html +++ b/documentation/osissues.html @@ -1,131 +1,208 @@ - -

F - Operating System Issues

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

X-Specific Interface

- + +

Despite the name, this header file will define the +appropriate interface for your environment. The pages that +follow describe the functionality that is provided for each +operating system. + +

+ + + +
WARNING: + +

The interfaces provided by this header file may + change radically in new FLTK releases. Use them only + when an existing generic FLTK interface is not + sufficient.

+ +
+ +

The UNIX (X11) Interface

+ +

The UNIX interface provides access to the X Window System +state information and data structures. +

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 -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 -non-zero (for example FL_SHORTCUT).

-

extern XEvent *fl_xvent

- 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. -

Window fl_xid(const Fl_Window *)

- 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. -

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). -

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(), -for instance) it will not return until the modal function returns.

+ +

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 event in the fl_xevent variable.

+ +

The argument is the FLTK event type that was not handled, or +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, for example +FL_SHORTCUT.

+ +

extern XEvent *fl_xvent

+ +

This variable contains the most recent X event. + +

extern ulong fl_event_time

+ +

This variable contains the time stamp from the most recent X +event that reported it; not all events 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(). + +

Fl_Window *fl_find(ulong xid)

+ +

Returns the Fl_Window that corresponds to the given +XID, or NULL if not found. This function 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 non-zero if FLTK understood the event. If the +window does not belong to FLTK and the add_handler() +functions all return 0, this function will return 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(), 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(): - + +

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. + +

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 RGB color. This is the X pixel that fl_color() would use. + +

extern XFontStruct *fl_xfont

+ +

Points to 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. +

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. -You may also want to call Fl::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. -

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. -

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 -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. -

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,#". -

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: - +

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, -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:

+ +

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 not shown() your implementation must call either -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 -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_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. + +

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_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. +

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 -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 -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 -region or NULL for no clipping. You must set region to -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 -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: - +

virtual void Fl_Window::~Fl_Window()

- Because of the way C++ works, if you override hide() you -must override the destructor as well (otherwise only the base class -hide() is called): - +

Setting the Icon of a Window

-FLTK currently supports setting a window's icon *before* it is shown -using the Fl_Window::icon() method. + +

FLTK currently supports setting a window's icon *before* it +is shown using the Fl_Window::icon() method. +

void Fl_Window::icon(char *)

-Sets the icon for the window to the passed pointer. You will need to -cast the icon Pixmap to a char * when calling this -method. To set the icon using a bitmap compiled with your application -use: - -

Note: you must call -Fl_Window::show(argc, argv) for the icon to be used. The -Fl_Window::show() method does not bind the icon to the window. +

+ + + +
NOTE: + +

You must call Fl_Window::show(argc, + argv) for the icon to be used. The + Fl_Window::show() method does not bind the icon + to the window. + +

+ +

The Windows (WIN32) Interface

+ +

The Windows interface provides access to the WIN32 GDI +state information and data structures. -

WIN32-Specific Interface

- - The <FL/x.H> header file defines the interface to FLTK's -WIN32-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 WIN32 Messages

- By default a single WNDCLASSEX called "FLTK" is created. All -Fl_Windows are of this class unless you use Fl_Window::xclass() -. The window class is created the first time Fl_Window::show() - is called. -

You can probably combine FLTK with other libraries that make their -own WIN32 window classes. The easiest way is to call Fl::wait() -, it will call DispatchMessage for all messages to the other -windows. If necessary you can let the other library take over (as long -as it calls DispatchMessage()), but you will have to arrange -for the function Fl::flush() to be called regularily so that -widgets are updated, timeouts are handled, and the idle functions are -called.

-

extern MSG fl_msg

- The most recent message read by GetMessage (which is called -by Fl::wait(). This may not -be the most recent message sent to an FLTK window, because silly WIN32 + +

By default a single WNDCLASSEX called "FLTK" is +created. All Fl_Window's are of this class unless you +use Fl_Window::xclass(). The window class is created +the first time Fl_Window::show() is called. + +

You can probably combine FLTK with other libraries that make +their own WIN32 window classes. The easiest way is to call +Fl::wait(), as it will call DispatchMessage +for all messages to the other windows. If necessary you can let +the other library take over as long as it calls +DispatchMessage(), but you will have to arrange for the +function Fl::flush() to be called regularly so that +widgets are updated, timeouts are handled, and the idle +functions are called.

+ +

extern MSG fl_msg

+ +

This variable contains the most recent message read by +GetMessage, which is called by Fl::wait(). This may not be the +most recent message sent to an FLTK window, because silly WIN32 calls the handle procedures directly for some events (sigh). -

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

- Install a function to parse unrecognized messages sent to FLTK -windows. If FLTK cannot figure out what to do with a message, it calls -each of these functions (most recent first) until one of them returns -non-zero. The argument passed to the fuctions is zero. If all the -handlers return zero then FLTK calls DefWindowProc(). -

HWND fl_xid(const Fl_Window *)

- Returns the window handle for a Fl_Window, or zero if not -shown(). -

Fl_Window *fl_find(HWND xid)

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

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

+ +

Installs a function to parse unrecognized messages sent to +FLTK windows. If FLTK cannot figure out what to do with a +message, it calls each of these functions (most recent first) +until one of them returns non-zero. The argument passed to the +functions is the FLTK event that was not handled or zero for +unknown messages. If all the handlers return zero then FLTK +calls DefWindowProc(). + +

HWND fl_xid(const Fl_Window *)

+ +

Returns the window handle for a Fl_Window, or zero +if not shown(). + +

Fl_Window *fl_find(HWND xid)

+ +

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

Drawing Things Using the WIN32 GDI

- When the virtual function Fl_Widget::draw() is called, FLTK -has stashed in some global variables all the silly extra arguments you -need to make a proper GDI call. These are: - + +

It may also be useful to refer to Fl_Window::current() +to get the window's size or position. +

Setting the Icon of a Window

- FLTK currently supports setting a window's icon *before* it is shown -using the Fl_Window::icon() method. + +

FLTK currently supports setting a window's icon *before* it +is shown using the Fl_Window::icon() method. +

void Fl_Window::icon(char *)

- Sets the icon for the window to the passed pointer. You will need to -cast the HICON handle to a char * when calling this -method. To set the icon using an icon resource compiled with your -application use: - + +

You can also use the LoadImage() and related +functions to load specific resolutions or create the icon from +bitmap data. -You can also use the LoadImage() and related functions to load -specific resolutions or create the icon from bitmap data. +

+ + + +
NOTE: + +

You must call Fl_Window::show(argc, + argv) for the icon to be used. The + Fl_Window::show() method does not bind the icon + to the window. -

Note: you must call -Fl_Window::show(argc, argv) for the icon to be used. The -Fl_Window::show() method does not bind the icon to the window. +

How to Not Get a MSDOS Console Window

- WIN32 has a really stupid mode switch stored in the executables that -controls whether or not to make a console window. + +

WIN32 has a really stupid mode switch stored in the +executables that controls whether or not to make a console +window. +

To always get a console window you simply create a console -application (the "/SUBSYSTEM:CONSOLE" option for the linker). For a -GUI-only application create a WIN32 application (the -"/SUBSYSTEM:WINDOWS" option for the linker).

-

FLTK includes a WinMain() function that calls the ANSI -standard main() entry point for you. This function creates -a console window when you use the debug version of the library.

-

WIN32 applications without a console cannot write to stdout - or stderr, even if they are run from a console window. Any -output is silently thrown away.

-

Known Bugs

- If a program is deactivated, Fl::wait() does not return until -it is activated again, even though many events are delivered to the -program. This can cause idle background processes to stop unexpectedly. - This also happens while the user is dragging or resizing windows or -otherwise holding the mouse down. I was forced to remove most of the -efficiency FLTK uses for redrawing in order to get windows to update -while being moved. This is a design error in WIN32 and probably -impossible to get around. -

Fl_Gl_Window::can_do_overlay() returns true until the first -time it attempts to draw an overlay, and then correctly returns whether -or not there is overlay hardware.

-

Cut text contains ^J rather than ^M^J to break lines. This is a -feature, not a bug.

-

SetCapture (used by Fl::grab()) doesn't work, and -the main window title bar turns gray while menus are popped up.

-

FLUID does not support BMP files yet.

- -

MacOS-specific interface

-FLTK supports MacOS 8.6, MacOS 9 and Mac OS X using the Apple Carbon library. -When compiled with MPW or MetroWerks' CodeWarrior, application binaries in CFM format will -run on all the above systems without changes. -OS X's 'gcc' however creates Mach-O binaries which are not supported by +application (the "/SUBSYSTEM:CONSOLE" option for the +linker). For a GUI-only application create a WIN32 application +(the "/SUBSYSTEM:WINDOWS" option for the linker).

+ +

FLTK includes a WinMain() function that calls the +ANSI standard main() entry point for you. This +function creates a console window when you use the debug version +of the library.

+ +

WIN32 applications without a console cannot write to +stdout or stderr, even if they are run from a +console window. Any output is silently thrown away. +Additionally, WIN32 applications are run in the background by +the console, although you can use "start /wait program" to run +them in the foreground.

+ +

Known WIN32 Bugs and Problems

+ +

The following is a list of known bugs and problems in the WIN32 +version of FLTK: + +

+ +

The MacOS Interface

+ +

FLTK supports MacOS 8.6, MacOS 9 and MacOS X using the Apple +Carbon library. When compiled with MPW or MetroWerks' +CodeWarrior, application binaries in CFM format will run on all +the above systems without changes. The OS X GNU (gcc) compiler, +however, creates Mach-O binaries which are not supported by MacOS 9 and earlier. -
-

#include <FL/x.H>
-The <FL/x.H> header file defines the interface to FLTK's MacOS-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. -

WindowRef fl_xid(const Fl_Window *)

-Returns the window reference for an Fl_Window, or NULL if not shown. + +

WindowRef fl_xid(const Fl_Window *)

+ +

Returns the window reference for an Fl_Window, or +NULL if the window has not been shown. +

Fl_Window *fl_find(WindowRef xid)

-Return the Fl_Window that corresponds to the give window hande, or NULL if not found. FLTK Windows that are children of top-level windows share the WindowRef -with the top-level window. + +

Returns the Fl_Window that corresponds to the give +window handle, or NULL if not found. FLTK windows that +are children of top-level windows share the WindowRef of the +top-level window. +

Drawing Things Using QuickDraw

-When the virtual function Fl_Widget::draw() is called, FLTK has prepared -the Window and CGrafPort for drawing. Clipping and offsets are prepared to allow -correct subwindow drawing. -

-OS X doublebuffers all windows automatically. On OS X Fl_Window and -Fl_Double_Window are handled internally in the same way. + +

When the virtual function Fl_Widget::draw() is +called, FLTK has prepared the Window and CGrafPort for drawing. +Clipping and offsets are prepared to allow correct subwindow +drawing. + +

OS X doublebuffers all windows automatically. On OS X, +Fl_Window and Fl_Double_Window are handled +internally in the same way. +

Mac File System Specifics

+

Resource Forks

-FLTK does not access the resource fork of an application. However, a minimal -resource fork must be created for OS 8 and OS X applications. + +

FLTK does not access the resource fork of an application. +However, a minimal resource fork must be created for OS 8 and OS +X applications. +

Mac File Paths

-FLTK uses Unix-style filenames and paths. - +

FLTK uses UNIX-style filenames and paths. + +

Known MacOS Bugs and Problems

+ +

The following is a list of known bugs and problems in the MacOS +version of FLTK: + +

+ + + -- cgit v1.2.3