From 87dd7f0d23eba5c09e71ec6efeb34c6844f5e95f Mon Sep 17 00:00:00 2001 From: Michael R Sweet Date: Tue, 29 Dec 1998 14:21:17 +0000 Subject: Revised documentation files. git-svn-id: file:///fltk/svn/fltk/trunk@177 ea41ed52-d2ee-0310-a9c1-e6b18d33e121 --- documentation/osissues.html | 455 ++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 455 insertions(+) create mode 100644 documentation/osissues.html (limited to 'documentation/osissues.html') diff --git a/documentation/osissues.html b/documentation/osissues.html new file mode 100644 index 000000000..f9cd36991 --- /dev/null +++ b/documentation/osissues.html @@ -0,0 +1,455 @@ + + + +

F - Operating System Specific Issues

+ +Fltk X-specific interface +

Fltk X-specific interface

+ +#include <FL/x.H> + +

On Unix/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));`

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

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 instance FL_SHORTCUT). + + +

Return 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 +it's 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

+ +

`+extern Display* fl_display; +extern Window fl_window; +extern GC fl_gc; +extern int fl_screen; +extern XVisualInfo* fl_visual; +extern Colormap fl_colormap;`

+ +These global variables are set before Fl_Widget::draw() is called, or +by

Fl_Window::make_current()

XDrawSomething(fl_display, fl_window, fl_gc, ...);

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);`

fl_color(i)

`unsigned long fl_xpixel(uchar r, uchar g, uchar +b);`

fl_color(r,g,b)

`extern XFontStruct* fl_xfont;`

fl_font(font,size)

fl_draw(const char*,...)

+ +

+ + +

Changing the display, screen, or X visual

+ +

Fltk uses only a single display, screen, X visual, and X colormap. +This greatly simplifies it's 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(int), which is a portable interface +to get a full color and/or double buffered visual. + +

`int Fl::display(const char *)`

setenv("DISPLAY", x)

`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 zero before the display is opened. + +

`void fl_open_display();`

fl_display

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

`void fl_close_display();`

not

`extern int fl_screen;`

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

+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);
+

+ +

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

`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 +set_xid with this new window and maps the window. + +

Example: + +

+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);
+}
+

`virtual void Fl_Window::flush()`

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 fl 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()==2 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: + +

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

`virtual void Fl_Window::hide()`

+void MyWindow::hide() {
+  if (mypixmap) {
+    XFreePixmap(fl_display,mypixmap);
+    mypixmap = 0;
+  }
+  Fl_Window::hide(); // you must call this
+}
+

`virtual void Fl_Window::~Fl_Window()`

must

+MyWindow::~MyWindow() {
+  hide();
+}
+

+ +

(back to contents) +Fltk MSWindows-specific interface +

#include <FL/x.H>
+Fltk MSWindows-specific interface

+ +The <FL/x.H> header file defines the interface to fltk's +MSWindows-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 MSWindows messages

+ +

A single WNDCLASSEX called "FLTK" is created. All +Fl_Windows are of this class. This window class is created the first +time Fl_Window::show() is called. + +

You can probably combine fltk with other libraries that make their +own MSWindows 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 (otherwise widgets will not +update), and timeouts and the idle function will not work. + + +

`extern MSG fl_msg;`

+ +The most recent message read by GetMessage (which is called by +

Fl::wait()

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

+ +

+ + +

Drawing things using the MSWindows 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: + +

`+extern HINSTANCE fl_display; +extern HWND fl_window; +extern HDC fl_gc; +COLORREF fl_RGB(); +HPEN fl_pen(); +HBRUSH fl_brush();`

+ +These global variables are set before draw() is called, or by

Fl_Window::make_current()

DrawSomething(fl_gc, ..., fl_brush());

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

How to not get a MSDOS console window

+ +MSWindows has a really stupid mode switch stored in the executables that +controls whether or not to make a console window (hint to Mr Gates: +why not leave it hidden until the program prints something?). + +

To not produce a "console" window when you run your program add the +following secret incantation to the Micro$oft linker: + +

        /SUBSYSTEM:WINDOWS /ENTRY:mainCRTStartup

+ +

Unfortunately this seems to completely disable stdin/stdout, even +if you run the program from a console. So don't do this until you +have debugged your program! + +

Other hints

+ +

I use capital C as the extension for c++ source code, for instace +for Fluid output. Unfortunately there is no way to convince VC++ to +use this except to tell it to compile *everything* using C++ by +putting the switch "/TP" in the options. This makes it impossible to +combine old C code and fltk code. + +

Known bugs

+ +

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

I can't seem to get SetCapture (used by Fl::grab()) to work, and I +can't find a way to stop the main window title from turning gray while +menus are popped up. + +

glpuzzle program does not animate unless you resize it first. Unknown why. + +

Fl_Window::fullscreen() not implemented (should take over the screen +without a title bar). Currently does maximize instead. + +

Import .bmp files into fluid. Wonko has the specs. + +

Can't set icon of windows. + + + + -- cgit v1.2.3

F - Operating System Specific Issues

Fltk X-specific interface

Handling other X events

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

Drawing using Xlib

+extern Display* fl_display; +extern Window fl_window; +extern GC fl_gc; +extern int fl_screen; +extern XVisualInfo* fl_visual; +extern Colormap fl_colormap;

unsigned long fl_xpixel(Fl_Color i);

unsigned long fl_xpixel(uchar r, uchar g, uchar +b);

extern XFontStruct* fl_xfont;

Changing the display, screen, or X visual

int Fl::display(const char *)

extern Display* fl_display;

void fl_open_display();

void fl_close_display();

extern int fl_screen;

extern XVisualInfo* fl_visual; +extern Colormap fl_colormap;

Using a subclass of Fl_Window for special X stuff

virtual void Fl_Window::show()

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

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

virtual void Fl_Window::flush()

virtual void Fl_Window::hide()

virtual void Fl_Window::~Fl_Window()

#include <FL/x.H> +Fltk MSWindows-specific interface

Handling other MSWindows messages

Drawing things using the MSWindows GDI

+extern HINSTANCE fl_display; +extern HWND fl_window; +extern HDC fl_gc; +COLORREF fl_RGB(); +HPEN fl_pen(); +HBRUSH fl_brush();

How to not get a MSDOS console window

Other hints

Known bugs

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

`+extern Display* fl_display; +extern Window fl_window; +extern GC fl_gc; +extern int fl_screen; +extern XVisualInfo* fl_visual; +extern Colormap fl_colormap;`

`unsigned long fl_xpixel(Fl_Color i);`

`unsigned long fl_xpixel(uchar r, uchar g, uchar +b);`

`extern XFontStruct* fl_xfont;`

`int Fl::display(const char *)`

`extern Display* fl_display;`

`void fl_open_display();`

`void fl_close_display();`

`extern int fl_screen;`

`extern XVisualInfo* fl_visual; +extern Colormap fl_colormap;`

`virtual void Fl_Window::show()`

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

`void Fl_X::make_xid(Fl_Window, XVisualInfo = +fl_visual, Colormap = fl_colormap);`

`virtual void Fl_Window::flush()`

`virtual void Fl_Window::hide()`

`virtual void Fl_Window::~Fl_Window()`

#include <FL/x.H>
+Fltk MSWindows-specific interface

`+extern HINSTANCE fl_display; +extern HWND fl_window; +extern HDC fl_gc; +COLORREF fl_RGB(); +HPEN fl_pen(); +HBRUSH fl_brush();`