From 501690edce2cecc356334fc42e7f429907cdfa1e Mon Sep 17 00:00:00 2001 From: Fabien Costantini Date: Fri, 17 Oct 2008 11:08:15 +0000 Subject: Last test does keep history, lets add all related files and patch them afterwards... git-svn-id: file:///fltk/svn/fltk/branches/branch-1.3@6447 ea41ed52-d2ee-0310-a9c1-e6b18d33e121 --- documentation/src_doc/osissues.dox | 765 +++++++++++++++++++++++++++++++++++++ 1 file changed, 765 insertions(+) create mode 100644 documentation/src_doc/osissues.dox (limited to 'documentation/src_doc/osissues.dox') diff --git a/documentation/src_doc/osissues.dox b/documentation/src_doc/osissues.dox new file mode 100644 index 000000000..b878d79d3 --- /dev/null +++ b/documentation/src_doc/osissues.dox @@ -0,0 +1,765 @@ +/** + + \page osissues F - Operating System Issues + +This appendix describes the operating system specific interfaces in FLTK. + +\section osissues_accessing Accessing the OS Interfaces + +All programs that need to access the operating system +specific interfaces must include the following header file: + +\code +#include +\endcode + +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. + +
+
+ +\section osissues_unit The UNIX (X11) Interface + +The UNIX interface provides access to the X Window System +state information and data structures. + +\subsection osissues_x_events 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 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. + +\subsection osissues_drawing_xlib Drawing using Xlib + +The following global variables are set before +Fl_Widget::draw() +is called, or by +Fl_Window::make_current(): + +\code +extern Display *fl_display; +extern Window fl_window; +extern GC fl_gc; +extern int fl_screen; +extern XVisualInfo *fl_visual; +extern Colormap fl_colormap; +\endcode + +You must use them to produce Xlib calls. Don't attempt to change +them. A typical X drawing call is written like this: + +\code +XDrawSomething(fl_display, fl_window, fl_gc, ...); +\endcode + +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. + + +int fl_parse_color(const char* p, uchar& r, uchar& g, uchar& b) + +Convert a name into the red, green, and blue values of a color +by parsing the X11 color names. On other systems, fl_parse_color +can only convert names in hexadecimal encoding, for example \#ff8083. + + +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. If FLTK was compiled with Xft support, fl_xfont +will usually be 0 and fl_xftfont will contain a pointer +to the XftFont structure instead. + + +extern void *fl_xftfont + +If FLTK was compiled with Xft support enabled, fl_xftfont +Points to the xft font selected by the most recent +fl_font(). +Otherwise it will be 0. fl_xftfont should be cast to +XftFont*. + +\subsection osissues_xvisual 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 MacOS and 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: + +\code +Fl::args(argc, argv); // do this first so $DISPLAY is set +fl_open_display(); +fl_visual = find_a_good_visual(fl_display, fl_screen); +if (!fl_visual) Fl::abort("No good visual"); +fl_colormap = make_a_colormap(fl_display, fl_visual->visual, fl_visual->depth); +// it is now ok to show() windows: +window->show(argc, argv); +\endcode + +\subsection osissues_specialx 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: + +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: + +\code +void MyWindow::show() { + if (shown()) {Fl_Window::show(); return;} // you must do this! + fl_open_display(); // necessary if this is first window + // we only calcualte the necessary visual colormap once: + static XVisualInfo *visual; + static Colormap colormap; + if (!visual) { + visual = figure_out_visual(); + colormap = XCreateColormap(fl_display, RootWindow(fl_display,fl_screen), + vis->visual, AllocNone); + } + Fl_X::make_xid(this, visual, colormap); +} +\endcode + +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. + +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() will own and 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: + +\code +void MyWindow::flush() { + fl_clip_region(Fl_X::i(this)->region); + Fl_X::i(this)->region = 0; + if (damage() != 2) {... draw things into backing store ...} + ... copy backing store to window ... +} +\endcode + +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: + +\code +void MyWindow::hide() { + if (mypixmap) { + XFreePixmap(fl_display,mypixmap); + mypixmap = 0; + } + Fl_Window::hide(); // you must call this +} +\endcode + +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): + +\code +MyWindow::~MyWindow() { + hide(); +} +\endcode + +\subsection osissues_x_icon Setting the Icon of a Window + +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 a monochrome icon using a bitmap compiled +with your application use: + +\code +#include "icon.xbm" + +fl_open_display(); // needed if display has not been previously opened + +Pixmap p = XCreateBitmapFromData(fl_display, DefaultRootWindow(fl_display), + icon_bits, icon_width, icon_height); + +window->icon((char *)p); +\endcode + +To use a multi-colored icon, the XPM format and library +should be used as follows: + +\code +#include +#include "icon.xpm" + +fl_open_display(); // needed if display has not been previously opened + +Pixmap p, mask; + +XpmCreatePixmapFromData(fl_display, DefaultRootWindow(fl_display), + icon_xpm, &p, &mask, NULL); + +window->icon((char *)p); +\endcode + +When using the Xpm library, be sure to include it in the list +of libraries that are used to link the application (usually "-lXpm"). + +
+ + + + +
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. + +
+
+ +\subsection osissues_xresources X Resources + +When the +Fl_Window::show(argc, argv) +method is called, FLTK looks for the following X resources: + +\li background - The default background color + for widgets (color). + +\li dndTextOps - The default setting for + drag and drop text operations (boolean). + +\li foreground - The default foreground (label) + color for widgets (color). + +\li scheme - The default scheme to use (string). + +\li selectBackground - The default selection + color for menus, etc. (color). + +\li Text.background - The default background + color for text fields (color). + +\li tooltips - The default setting for + tooltips (boolean). + +\li visibleFocus - The default setting for + visible keyboard focus on non-text widgets (boolean). + +Resources associated with the first window's +Fl_Window::xclass() +string are queried first, or if no class has been specified then +the class "fltk" is used (e.g. fltk.background). If no +match is found, a global search is done (e.g. +*background). + +\section osissues_win32 The Windows (WIN32) Interface + +The Windows interface provides access to the WIN32 GDI +state information and data structures. + +\subsection osissues_win32_messages Handling Other WIN32 Messages + +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)) + +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. + + +\subsection osissues_win32_gdi Drawing Things Using the WIN32 GDI + +When the virtual function +Fl_Widget::draw() is +called, FLTK stores all the silly extra arguments you need to +make a proper GDI call in some global variables: + +\code +extern HINSTANCE fl_display; +extern HWND fl_window; +extern HDC fl_gc; +COLORREF fl_RGB(); +HPEN fl_pen(); +HBRUSH fl_brush(); +\endcode + +These global variables are set before draw() is called, or by +Fl_Window::make_current(). +You can refer to them when needed to produce GDI calls, but don't +attempt to change them. The functions return GDI objects for +the current color set by fl_color() and are created as +needed and cached. A typical GDI drawing call is written like +this: + +\code +DrawSomething(fl_gc, ..., fl_brush()); +\endcode + +It may also be useful to refer to +Fl_Window::current() +to get the window's size or position. + +\subsection osissues_icon_windows Setting the Icon of a Window + +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: + +\code +window->icon((char *)LoadIcon(fl_display, MAKEINTRESOURCE(IDI_ICON))); +\endcode + +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. + +
+
+ +\subsection osissues_msdos_console 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. + +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. +Additionally, WIN32 applications are run in the background by +the console, although you can use "start /wait program" to run +them in the foreground. + +\subsection osissues_win32_problems Known WIN32 Bugs and Problems + +The following is a list of known bugs and problems in the WIN32 +version of FLTK: + +\li 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. We were + 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. + +\li 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. + +\li SetCapture (used by Fl::grab()) + doesn't work, and the main window title bar turns gray + while menus are popped up. + +\li Compilation with gcc 3.4.4 and -Os exposes an + optimisation bug in gcc. The symptom is that when drawing + filled circles only the perimeter is drawn. This can for instance + be seen in the symbols demo. Other optimisation options such + as -O2 and -O3 seem to work OK. More details can be found + in STR#1656 + +\section osissues_macos The MacOS Interface + +FLTK supports MacOS X using the Apple Carbon library. Older +versions of MacOS are not supported. + +\par Control, Option, and Command Modifier Keys + +FLTK maps the Mac 'control' key to FL_CTRL, the +'option' key to FL_ALT and the 'Apple' key to +FL_META. Keyboard events return the key name in +Fl::event_key() and the keystroke translation in +Fl::event_text(). For example, typing Option-Y on a Mac +keyboard will set FL_ALT in Fl::event_state(), +set Fl::event_key() to 'y' and return the Yen symbol in +Fl::event_text(). + +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) + +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. + +\subsection osissues_apple_quit Apple "Quit" Event + +When the user press Cmd-Q or requests a termination of the +application, OS X will send a "Quit" Apple Event. FLTK handles +this event by sending an FL_CLOSE event to all open +windows. If all windows close, the application will terminate. + +\subsection osissues_apple_open Apple "Open" Event + +Whenever the user drops a file onto an application icon, OS X +generates an Apple Event of the type "Open". You can have FLTK +notify you of an Open event by setting the fl_open_callback. + + +void fl_open_callback(void (*cb)(const char *)) + +cb will be called with a single iUnix-style file name and path. +If multiple files were dropped, fl_open_callback will be called +multiple times. + +\subsection osissues_quickdraw 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. + +\subsection osissues_quartz Drawing Things Using Quartz + +If the FLTK library was compiled using the configuration +flag --enable-quartz, all code inside Fl_Widget::draw() +is expected to call Quartz drawing functions instead of +QuickDraw. The Quartz coordinate system is flipped to match +FLTK's coordinate system. The origin for all drawing is in the top +left corner of the enclosing Fl_Window. + +Fl_Double_Window + +OS X double-buffers all windows automatically. On OS X, +Fl_Window and Fl_Double_Window are handled +internally in the same way. + +\subsection osissues_mac_files Mac File System Specifics + +\par Resource Forks + +FLTK does not access the resource fork of an application. +However, a minimal resource fork must be created for OS X +applications + +
+ +
Caution: + +When using UNIX commands to copy or move executables, OS X +will NOT copy any resource forks! For copying and moving use +CpMac and MvMac respectively. For creating a tar archive, all +executables need to be stripped from their Resource Fork before +packing, e.g. "DeRez fluid > fluid.r". After unpacking the +Resource Fork needs to be reattached, e.g. "Rez fluid.r -o +fluid". +
+
+ +It is advisable to use the Finder for moving and copying and +Mac archiving tools like Sit for distribution as they will +handle the Resource Fork correctly. + +\par Mac File Paths + +FLTK uses UNIX-style filenames and paths. + +\subsection osissues_macos_problems Known MacOS Bugs and Problems + +The following is a list of known bugs and problems in the +MacOS version of FLTK: + +\li Line styles are not well supported. This is due to + limitations in the QuickDraw interface. + +\li Nested subwindows are not supported, i.e. you can + have a Fl_Window widget inside a + Fl_Window, but not a Fl_Window inside a + Fl_Window inside a Fl_Window. + +\htmlonly +
+[Index]    +[Previous]  + \ref forms    +[Next]  + \ref migration_1_1 + +\endhtmlonly +*/ -- cgit v1.2.3