From d658ae60392ed57eedd3ada08717e4947768934e Mon Sep 17 00:00:00 2001 From: engelsman Date: Fri, 10 Oct 2008 20:17:33 +0000 Subject: converted more html to plain doxygen in {events,subclassing,opengl}.dox git-svn-id: file:///fltk/svn/fltk/branches/branch-1.3@6406 ea41ed52-d2ee-0310-a9c1-e6b18d33e121 --- documentation/events.dox | 411 ++++++++++++++++--------------- documentation/opengl.dox | 319 ++++++++++++------------ documentation/subclassing.dox | 551 +++++++++++++++++++++++++----------------- 3 files changed, 681 insertions(+), 600 deletions(-) (limited to 'documentation') diff --git a/documentation/events.dox b/documentation/events.dox index 6f4db3c1c..f41628bdf 100644 --- a/documentation/events.dox +++ b/documentation/events.dox @@ -2,269 +2,273 @@ \page events 6 - Handling Events -

This chapter discusses the FLTK event model and how to handle +This chapter discusses the FLTK event model and how to handle events in your program or widget. -

The FLTK Event Model

+\section events_model The FLTK Event Model -

Every time a user moves the mouse pointer, clicks a button, +Every time a user moves the mouse pointer, clicks a button, or presses a key, an event is generated and sent to your application. Events can also come from other programs like the window manager. -

Events are identified by the integer argument passed to the -Fl_Widget::handle() virtual +Events are identified by the integer argument passed to the +Fl_Widget::handle() +virtual method. Other information about the most recent event is stored in static locations and acquired by calling the \ref events_event_xxx methods. This static information remains valid until the next event is read from the window system, so it is ok to look at it outside -of the handle() method. +of the handle() method. -

Mouse Events

+\section events_mouse Mouse Events -

FL_PUSH

+\subsection events_fl_push FL_PUSH -

A mouse button has gone down with the mouse pointing at this -widget. You can find out what button by calling -Fl::event_button(). You find out the mouse position by -calling Fl::event_x() and Fl::event_y(). +A mouse button has gone down with the mouse pointing at this +widget. You can find out what button by calling +Fl::event_button(). +You find out the mouse position by calling +Fl::event_x() +and + Fl::event_y(). -

A widget indicates that it "wants" the mouse click -by returning non-zero from its handle() method. It -will then become the -Fl::pushed() widget and will get FL_DRAG and -the matching FL_RELEASE events. If handle() -returns zero then FLTK will try sending the FL_PUSH to -another widget.

+A widget indicates that it "wants" the mouse click +by returning non-zero from its +handle() +method. It will then become the +Fl::pushed() +widget and will get FL_DRAG and +the matching FL_RELEASE events. If handle() +returns zero then FLTK will try sending the FL_PUSH to +another widget. -

FL_DRAG

+\subsection events_fl_drag FL_DRAG -

The mouse has moved with a button held down. The current -button state is in Fl::event_state(). -The mouse position is in Fl::event_x() and Fl::event_y(). +The mouse has moved with a button held down. The current +button state is in +Fl::event_state(). +The mouse position is in +Fl::event_x() +and +Fl::event_y(). -

In order to receive FL_DRAG events, the widget must -return non-zero when handling FL_PUSH.

+In order to receive FL_DRAG events, the widget must +return non-zero when handling FL_PUSH. -

FL_RELEASE

+\subsection events_fl_release FL_RELEASE -

A mouse button has been released. You can find out what -button by calling Fl::event_button(). +A mouse button has been released. You can find out what button by calling +Fl::event_button(). -

In order to receive the FL_RELEASE event, the widget must -return non-zero when handling FL_PUSH.

+In order to receive the FL_RELEASE event, the widget must +return non-zero when handling FL_PUSH. -

FL_MOVE

+\subsection events_fl_move FL_MOVE -

The mouse has moved without any mouse buttons held down. -This event is sent to the Fl::belowmouse() -widget.

+The mouse has moved without any mouse buttons held down. +This event is sent to the +Fl::belowmouse() +widget. -

In order to receive FL_MOVE events, the widget must -return non-zero when handling FL_ENTER.

+In order to receive FL_MOVE events, the widget must +return non-zero when handling FL_ENTER. -

FL_MOUSEWHEEL

+\subsection events_fl_mousewheel FL_MOUSEWHEEL -

The user has moved the mouse wheel. The Fl::event_dx() and Fl::event_dy() methods -can be used to find the amount to scroll horizontally and +The user has moved the mouse wheel. The +Fl::event_dx() +and +Fl::event_dy() +methods can be used to find the amount to scroll horizontally and vertically. -

Focus Events

+\section events_focus Focus Events -

FL_ENTER

+\subsection events_fl_enter FL_ENTER -

The mouse has been moved to point at this widget. This can +The mouse has been moved to point at this widget. This can be used for highlighting feedback. If a widget wants to highlight or otherwise track the mouse, it indicates this by -returning non-zero from its handle() method. It then -becomes the Fl::belowmouse() -widget and will receive FL_MOVE and FL_LEAVE +returning non-zero from its +handle() +method. It then becomes the +Fl::belowmouse() +widget and will receive FL_MOVE and FL_LEAVE events. -

FL_LEAVE

+\subsection events_fl_leave FL_LEAVE -

The mouse has moved out of the widget. +The mouse has moved out of the widget. -

In order to receive the FL_LEAVE event, the widget must -return non-zero when handling FL_ENTER.

+In order to receive the FL_LEAVE event, the widget must +return non-zero when handling FL_ENTER. -

FL_FOCUS

+\subsection events_fl_focus FL_FOCUS -

This indicates an attempt to give a widget the +This indicates an attempt to give a widget the keyboard focus. -

If a widget wants the focus, it should change itself to -display the fact that it has the focus, and return non-zero from -its handle() -method. It then becomes the Fl::focus() widget and gets -FL_KEYDOWN, FL_KEYUP, and FL_UNFOCUS +If a widget wants the focus, it should change itself to +display the fact that it has the focus, and return non-zero from its +handle() +method. It then becomes the +Fl::focus() +widget and gets +FL_KEYDOWN, FL_KEYUP, and FL_UNFOCUS events. -

The focus will change either because the window manager +The focus will change either because the window manager changed which window gets the focus, or because the user tried -to navigate using tab, arrows, or other keys. You can check Fl::event_key() to -figure out why it moved. For navigation it will be the key -pressed and interaction with the window manager it will be -zero. +to navigate using tab, arrows, or other keys. You can check +Fl::event_key() +to figure out why it moved. For navigation it will be the key +pressed and interaction with the window manager it will be zero. -

FL_UNFOCUS

+\subsection events_fl_unfocus FL_UNFOCUS -

This event is sent to the previous Fl::focus() widget when -another widget gets the focus or the window loses focus. +This event is sent to the previous +Fl::focus() +widget when another widget gets the focus or the window loses focus. -

Keyboard Events

+\section events_keyboard Keyboard Events -

FL_KEYDOWN, FL_KEYUP

+\subsection events_fl_keydown FL_KEYDOWN, FL_KEYUP -

A key was pressed or released. The key can be found in Fl::event_key(). The -text that the key should insert can be found with Fl::event_text() and -its length is in Fl::event_length(). -If you use the key handle() should return 1. If you +A key was pressed or released. The key can be found in +Fl::event_key(). +The text that the key should insert can be found with +Fl::event_text() +and its length is in +Fl::event_length(). +If you use the key handle() should return 1. If you return zero then FLTK assumes you ignored the key and will then attempt to send it to a parent widget. If none of them want -it, it will change the event into a FL_SHORTCUT event. +it, it will change the event into a FL_SHORTCUT event. -

To receive FL_KEYBOARD events you must also +To receive FL_KEYBOARD events you must also respond to the FL_FOCUS and FL_UNFOCUS events. -

If you are writing a text-editing widget you may also want to -call the Fl::compose() -function to translate individual keystrokes into foreign -characters. +If you are writing a text-editing widget you may also want to +call the +Fl::compose() +function to translate individual keystrokes into foreign characters. -

FL_KEYUP events are sent to the widget that +FL_KEYUP events are sent to the widget that currently has focus. This is not necessarily the same widget that received the corresponding FL_KEYDOWN event because focus may have changed between events. -

FL_SHORTCUT

+\subsection events_fl_shortcut FL_SHORTCUT -

If the Fl::focus() -widget is zero or ignores an FL_KEYBOARD event then +If the +Fl::focus() +widget is zero or ignores an FL_KEYBOARD event then FLTK tries sending this event to every widget it can, until one -of them returns non-zero. FL_SHORTCUT is first sent to -the Fl::belowmouse() widget, then its parents and +of them returns non-zero. FL_SHORTCUT is first sent to +the Fl::belowmouse() widget, then its parents and siblings, and eventually to every widget in the window, trying to find an object that returns non-zero. FLTK tries really hard to not to ignore any keystrokes! -

You can also make "global" shortcuts by using Fl::add_handler(). A -global shortcut will work no matter what windows are displayed -or which one has the focus.

+You can also make "global" shortcuts by using +Fl::add_handler(). +A global shortcut will work no matter what windows are displayed +or which one has the focus. -

Widget Events

+\section events_widget Widget Events -

FL_DEACTIVATE

+\subsection events_fl_deactivate FL_DEACTIVATE -

This widget is no longer active, due to deactivate() -being called on it or one of its parents. active() may +This widget is no longer active, due to +deactivate() +being called on it or one of its parents. active() may still be true after this, the widget is only active if -active() is true on it and all its parents (use active_r() to check this). +active() is true on it and all its parents (use active_r() to check this). -

FL_ACTIVATE

+\subsection events_fl_activate FL_ACTIVATE -

This widget is now active, due to activate() +This widget is now active, due to +activate() being called on it or one of its parents. -

FL_HIDE

+\subsection events_fl_hide FL_HIDE -

This widget is no longer visible, due to hide() being -called on it or one of its parents, or due to a parent window +This widget is no longer visible, due to +hide() +being called on it or one of its parents, or due to a parent window being minimized. visible() may still be true after this, but the widget is visible only if visible() is true for it and all its parents (use visible_r() to check this). -

FL_SHOW

+\subsection events_fl_show FL_SHOW -

This widget is visible again, due to show() being -called on it or one of its parents, or due to a parent window -being restored. Child Fl_Windows respond to this by +This widget is visible again, due to +show() +being called on it or one of its parents, or due to a parent window +being restored. Child Fl_Windows respond to this by actually creating the window if not done already, so if you -subclass a window, be sure to pass FL_SHOW to the base -class handle() method! +subclass a window, be sure to pass FL_SHOW to the base +class handle() method! -

Clipboard Events

+\section events_clipboard Clipboard Events -

FL_PASTE

+\subsection events_fl_paste FL_PASTE -

You should get this event some time after you call Fl::paste(). The contents -of Fl::event_text() -is the text to insert and the number of characters is in Fl::event_length(). +You should get this event some time after you call +Fl::paste(). +The contents of +Fl::event_text() +is the text to insert and the number of characters is in +Fl::event_length(). -

FL_SELECTIONCLEAR

+\subsection events_fl_selectionclear FL_SELECTIONCLEAR -

The Fl::selection_owner() +The Fl::selection_owner() will get this event before the selection is moved to another widget. This indicates that some other widget or program has claimed the selection. Motif programs used this to clear the selection indication. Most modern programs ignore this. -

Drag And Drop Events

+ +\section events_dnd Drag and Drop Events -

FLTK supports drag and drop of text and files from any +FLTK supports drag and drop of text and files from any application on the desktop. Text is transfered using the current code page. Files are received as a list of full path and file names, seperated by newline. On some platforms, path names are prepended with file://. -

The drag and drop data is available in Fl::event_text() +The drag and drop data is available in Fl::event_text() at the concluding FL_PASTE. On some platforms, the event text is also available for the FL_DND_* events, however application must not depend on that behavior because it depends on the protocol used on each platform. -

FL_DND_* events cannot be used in widgets derived +FL_DND_* events cannot be used in widgets derived from Fl_Group or Fl_Window. -

FL_DND_ENTER

+\subsection events_fl_dnd_enter FL_DND_ENTER -

The mouse has been moved to point at this widget. A widget +The mouse has been moved to point at this widget. A widget that is interested in receiving drag'n'drop data must return 1 to receive FL_DND_DRAG, FL_DND_LEAVE and FL_DND_RELEASE events. -

FL_DND_DRAG

+\subsection events_fl_dnd_drag FL_DND_DRAG -

The mouse has been moved inside a widget while dragging data. +The mouse has been moved inside a widget while dragging data. A widget that is interested in receiving drag'n'drop data should indicate the possible drop position. -

FL_DND_LEAVE

+\subsection events_fl_dnd_leave FL_DND_LEAVE -

The mouse has moved out of the widget. +The mouse has moved out of the widget. -

FL_DND_RELEASE

+\subsection events_fl_dnd_release FL_DND_RELEASE -

The user has released the mouse button dropping data into +The user has released the mouse button dropping data into the widget. If the widget returns 1, it will receive the data in the immediatly following FL_PASTE event. @@ -273,119 +277,108 @@ the immediatly following FL_PASTE event. \section events_event_xxx Fl::event_*() methods -

FLTK keeps the information about the most recent event in +FLTK keeps the information about the most recent event in static storage. This information is good until the next event is -processed. Thus it is valid inside handle() and -callback() methods. - -

These are all trivial inline functions and thus very fast and small:

+processed. Thus it is valid inside handle() and +callback() methods. - +\li Fl::test_shortcut \section events_propagation Event Propagation -

FLTK follows very simple and unchangeable rules for sending +FLTK follows very simple and unchangeable rules for sending events. The major innovation is that widgets can indicate (by -returning 0 from the handle() method) that they are not +returning 0 from the handle() method) that they are not interested in an event, and FLTK can then send that event elsewhere. This eliminates the need for "interests" (event masks or tables), and this is probably the main reason FLTK is much smaller than other toolkits. -

Most events are sent directly to the handle() method -of the Fl_Window that the window system says they -belong to. The window (actually the Fl_Group that -Fl_Window is a subclass of) is responsible for sending +Most events are sent directly to the handle() method +of the Fl_Window that the window system says they +belong to. The window (actually the Fl_Group that +Fl_Window is a subclass of) is responsible for sending the events on to any child widgets. To make the -Fl_Group code somewhat easier, FLTK sends some events -(FL_DRAG, FL_RELEASE, FL_KEYBOARD, -FL_SHORTCUT, FL_UNFOCUS, and -FL_LEAVE) directly to leaf widgets. These procedures +Fl_Group code somewhat easier, FLTK sends some events +(FL_DRAG, FL_RELEASE, FL_KEYBOARD, +FL_SHORTCUT, FL_UNFOCUS, and +FL_LEAVE) directly to leaf widgets. These procedures control those leaf widgets: -

+ +\section events_compose_characters FLTK Compose-Character Sequences -

FLTK Compose-Character Sequences

+The foreign-letter compose processing done by the +Fl_Input +widget is provided in a function that you can call if you are writing +your own text editor widget. -

The foreign-letter compose processing done by the Fl_Input widget is provided in -a function that you can call if you are writing your own text editor -widget. - -

FLTK uses its own compose processing to allow "preview" of +FLTK uses its own compose processing to allow "preview" of the partially composed sequence, which is impossible with the usual "dead key" processing. -

Although currently only characters in the ISO-8859-1 +Although currently only characters in the ISO-8859-1 character set are handled, you should call this in case any enhancements to the processing are done in the future. The interface has been designed to handle arbitrary UTF-8 encoded text. -

The following methods are provided for character composition: - -

+\li Fl::compose_reset()
[Index]    diff --git a/documentation/opengl.dox b/documentation/opengl.dox index c06d1bb4d..4fd6d6ec0 100644 --- a/documentation/opengl.dox +++ b/documentation/opengl.dox @@ -2,46 +2,42 @@ \page opengl 8 - Using OpenGL -

This chapter discusses using FLTK for your OpenGL applications. +This chapter discusses using FLTK for your OpenGL applications. -

Using OpenGL in FLTK

+\section opengl_using Using OpenGL in FLTK -

The easiest way to make an OpenGL display is to subclass Fl_Gl_Window. -Your subclass must implement a draw() method which uses +The easiest way to make an OpenGL display is to subclass +Fl_Gl_Window. +Your subclass must implement a draw() method which uses OpenGL calls to draw the display. Your main program should call -redraw() when the display needs to change, and -(somewhat later) FLTK will call draw(). +redraw() when the display needs to change, and +(somewhat later) FLTK will call draw(). -

With a bit of care you can also use OpenGL to draw into +With a bit of care you can also use OpenGL to draw into normal FLTK windows. This allows you to use Gouraud shading for -drawing your widgets. To do this you use the gl_start() and gl_finish() functions around your -OpenGL code.

- -

You must include FLTK's header -file. It will include the file , define +drawing your widgets. To do this you use the +gl_start() +and +gl_finish() +functions around your OpenGL code. + +You must include FLTK's header +file. It will include the file , define some extra drawing functions provided by FLTK, and include the - header file needed by WIN32 -applications.

- -

Making a Subclass of Fl_Gl_Window

- -

To make a subclass of Fl_Gl_Window, you must provide: + header file needed by WIN32 +applications. -

+\li A handle() method if you need to receive input from the user. -

If your subclass provides static controls in the window, they +If your subclass provides static controls in the window, they must be redrawn whenever the FL_DAMAGE_ALL bit is set in the value returned by damage(). For double-buffered windows you will need to surround the drawing code with the @@ -72,10 +68,9 @@ glDrawBuffer(GL_BACK); -

Defining the Subclass

+\subsection opengl_defining Defining the Subclass -

To define the subclass you just subclass the -Fl_Gl_Window class: +To define the subclass you just subclass the Fl_Gl_Window class: \code class MyWindow : public Fl_Gl_Window { @@ -88,15 +83,14 @@ public: }; \endcode -

The draw() and handle() methods are +The draw() and handle() methods are described below. Like any widget, you can include additional private and public data in your class (such as scene graph information, etc.) -

The draw() Method

+\subsection opengl_draw The draw() Method -

The draw() method is where you actually do your -OpenGL drawing: +The draw() method is where you actually do your OpenGL drawing: \code void MyWindow::draw() { @@ -109,9 +103,9 @@ void MyWindow::draw() { } \endcode -

The handle() Method

+\subsection opengl_handle The handle() Method -

The handle() method handles mouse and keyboard +The handle() method handles mouse and keyboard events for the window: \code @@ -146,13 +140,13 @@ int MyWindow::handle(int event) { } \endcode -

When handle() is called, the OpenGL context is not +When handle() is called, the OpenGL context is not set up! If your display changes, you should call -redraw() and let draw() do the work. Don't -call any OpenGL drawing functions from inside handle()! +redraw() and let draw() do the work. Don't +call any OpenGL drawing functions from inside handle()! -

You can call some OpenGL stuff like hit detection and texture -loading functions by doing:

+You can call some OpenGL stuff like hit detection and texture +loading functions by doing: \code case FL_PUSH: @@ -167,50 +161,44 @@ loading functions by doing:

detection, loading textures, etc... \endcode -

Your main program can now create one of your windows by doing -new MyWindow(...). You can also use FLUID by: - -

    - -
  1. Putting your class definition in a - MyWindow.H file.
    2. - -
  2. Creating a Fl_Box widget in FLUID.
    3. - -
  3. In the widget panel fill in the "class" - field with MyWindow. This will make FLUID - produce constructors for your new class.
    4. - -
  4. In the "Extra Code" field put \#include - "MyWindow.H", so that the FLUID output - file will compile.
    5. - -
- -

You must put glwindow->show() in your main code -after calling show() on the window containing the +Your main program can now create one of your windows by doing +new MyWindow(...). You can also use +FLUID +by: + +-# Putting your class definition in a MyWindow.H file. +
+-# Creating a Fl_Box widget in FLUID. +
+-# In the widget panel fill in the "class" field with MyWindow. + This will make FLUID produce constructors for your new class. +
+-# In the "Extra Code" field put \#include "MyWindow.H", + so that the FLUID output file will compile. + +You must put glwindow->show() in your main code +after calling show() on the window containing the OpenGL window. -

Using OpenGL in Normal FLTK Windows

+\section opengl_normal Using OpenGL in Normal FLTK Windows -

You can put OpenGL code into an Fl_Widget::draw() -method or into the code for a boxtype or other places with some -care. +You can put OpenGL code into an +Fl_Widget::draw() +method or into the code for a +boxtype +or other places with some care. -

Most importantly, before you show any windows, +Most importantly, before you show any windows, including those that don't have OpenGL drawing, you must initialize FLTK so that it knows it is going to use OpenGL. You may use any of the symbols described for Fl_Gl_Window::mode() -to describe how you intend to use OpenGL:

+to describe how you intend to use OpenGL: \code Fl::gl_visual(FL_RGB); \endcode -

You can then put OpenGL drawing code anywhere you can draw +You can then put OpenGL drawing code anywhere you can draw normally by surrounding it with: \code @@ -219,143 +207,145 @@ gl_start(); gl_finish(); \endcode -

gl_start() and gl_finish() set up an OpenGL +gl_start() +and +gl_finish() +set up an OpenGL context with an orthographic projection so that 0,0 is the lower-left corner of the window and each pixel is one unit. The -current clipping is reproduced with OpenGL glScissor() +current clipping is reproduced with OpenGL glScissor() commands. These functions also synchronize the OpenGL graphics stream with the drawing done by other X, WIN32, or FLTK functions. -

The same context is reused each time. If your code changes +The same context is reused each time. If your code changes the projection transformation or anything else you should use -glPushMatrix() and glPopMatrix() functions to -put the state back before calling gl_finish().

+glPushMatrix() and glPopMatrix() functions to +put the state back before calling gl_finish(). -

You may want to use Fl_Window::current()->h() to +You may want to use Fl_Window::current()->h() to get the drawable height so that you can flip the Y -coordinates.

+coordinates. -

Unfortunately, there are a bunch of limitations you must -adhere to for maximum portability:

+Unfortunately, there are a bunch of limitations you must +adhere to for maximum portability: - +\section opengl_drawing OpenGL Drawing Functions -

Do not call gl_start() or -gl_finish() when drawing into an Fl_Gl_Window ! - -

OpenGL Drawing Functions

- -

FLTK provides some useful OpenGL drawing functions. They can +FLTK provides some useful OpenGL drawing functions. They can be freely mixed with any OpenGL calls, and are defined by including which you should include -instead of the OpenGL header . +instead of the OpenGL header . -

void gl_color(Fl_Color)

+void gl_color(Fl_Color) -

Sets the current OpenGL color to a FLTK color. For -color-index modes it will use fl_xpixel(c), which is +\par +Sets the current OpenGL color to a FLTK color. For +color-index modes it will use fl_xpixel(c), which is only right if this window uses the default colormap! -

void gl_rect(int x, int y, int w, int h) -
void gl_rectf(int x, int y, int w, int h)

+void gl_rect(int x, int y, int w, int h)
+void gl_rectf(int x, int y, int w, int h) -

Outlines or fills a rectangle with the current color. If +\par +Outlines or fills a rectangle with the current color. If Fl_Gl_Window::ortho() has been called, then the rectangle will exactly fill the pixel rectangle passed. -

void gl_font(Fl_Font fontid, int size)

+void gl_font(Fl_Font fontid, int size) -

Sets the current OpenGL font to the same font you get by -calling fl_font(). +\par +Sets the current OpenGL font to the same font you get by calling +fl_font(). -

int gl_height() -
int gl_descent() -
float gl_width(const char *) -
float gl_width(const char *, int n) -
float gl_width(uchar)

+int gl_height()
+int gl_descent()
+float gl_width(const char *)
+float gl_width(const char *, int n)
+float gl_width(uchar) -

Returns information about the current OpenGL font. +\par +Returns information about the current OpenGL font. -

void gl_draw(const char *) -
void gl_draw(const char *, int n)

+void gl_draw(const char *)
+void gl_draw(const char *, int n) -

Draws a nul-terminated string or an array of n +\par +Draws a nul-terminated string or an array of n characters in the current OpenGL font at the current raster position. -

void gl_draw(const char *, int x, int y) -
void gl_draw(const char *, int n, int x, int y) -
void gl_draw(const char *, float x, float y) -
void gl_draw(const char *, int n, float x, float y)

+void gl_draw(const char *, int x, int y)
+void gl_draw(const char *, int n, int x, int y)
+void gl_draw(const char *, float x, float y)
+void gl_draw(const char *, int n, float x, float y) -

Draws a nul-terminated string or an array of n +\par +Draws a nul-terminated string or an array of n characters in the current OpenGL font at the given position. -

void gl_draw(const char *, int x, int y, int w, int h, Fl_Align)

+void gl_draw(const char *, int x, int y, int w, int h, Fl_Align) -

Draws a string formatted into a box, with newlines and tabs +\par +Draws a string formatted into a box, with newlines and tabs expanded, other control characters changed to ^X, and aligned -with the edges or center. Exactly the same output as fl_draw(). +with the edges or center. Exactly the same output as +fl_draw(). -

Speeding up OpenGL

+\section opengl_speed Speeding up OpenGL -

Performance of Fl_Gl_Window may be improved on some types of +Performance of Fl_Gl_Window may be improved on some types of OpenGL implementations, in particular MESA and other software emulators, by setting the GL_SWAP_TYPE environment variable. This variable declares what is in the backbuffer after you do a swapbuffers. -

- -

This is easily tested by running the gl_overlay demo +\li setenv GL_SWAP_TYPE COPY
+
+ This indicates that the back buffer is copied to the + front buffer, and still contains it's old data. This is + true of many hardware implementations. Setting this + will speed up emulation of overlays, and widgets that + can do partial update can take advantage of this as + damage() will not be cleared to -1.

+ +\li setenv GL_SWAP_TYPE NODAMAGE
+
+ This indicates that nothing changes the back buffer + except drawing into it. This is true of MESA and Win32 + software emulation and perhaps some hardware emulation + on systems with lots of memory.

+ +\li All other values for GL_SWAP_TYPE, and not + setting the variable, cause FLTK to assume that the + back buffer must be completely redrawn after a swap. + +This is easily tested by running the gl_overlay demo program and seeing if the display is correct when you drag another window over it or if you drag the window off the screen and back on. You have to exit and run the program again for it to see any changes to the environment variable. -

Using OpenGL Optimizer with FLTK

+\section opengl_optimizer Using OpenGL Optimizer with FLTK -

OpenGL -Optimizer is a scene graph toolkit for OpenGL available from +OpenGL Optimizer +is a scene graph toolkit for OpenGL available from Silicon Graphics for IRIX and Microsoft Windows. It allows you to view large scenes without writing a lot of OpenGL code. -

OptimizerWindow Class Definition

+\par OptimizerWindow Class Definition -

To use OpenGL Optimizer with FLTK you'll need to create a -subclass of Fl_Gl_Widget that includes several state +\par +To use OpenGL Optimizer with FLTK you'll need to create a +subclass of Fl_Gl_Widget that includes several state variables: \code @@ -389,15 +379,17 @@ public: }; \endcode -

The camera() Method

+\par The camera() Method -

The camera() method sets the camera (projection and +\par +The camera() method sets the camera (projection and viewpoint) to use when drawing the scene. The scene is redrawn after this call. -

The draw() Method

+\par The draw() Method -

The draw() method performs the needed initialization and does +\par +The draw() method performs the needed initialization and does the actual drawing: \code @@ -451,10 +443,11 @@ void OptimizerWindow::draw() { } \endcode -

The scene() Method

+\par The scene() Method -

The scene() method sets the scene to be drawn. The scene is -a collection of 3D objects in a csGroup. The scene is redrawn +\par +The scene() method sets the scene to be drawn. The scene is +a collection of 3D objects in a csGroup. The scene is redrawn after this call.

diff --git a/documentation/subclassing.dox b/documentation/subclassing.dox index 865f58cb8..4b9cf82d0 100644 --- a/documentation/subclassing.dox +++ b/documentation/subclassing.dox @@ -2,46 +2,63 @@ \page subclassing 7 - Adding and Extending Widgets -

This chapter describes how to add your own widgets or extend existing + +This chapter describes how to add your own widgets or extend existing widgets in FLTK. -

Subclassing

- New widgets are created by subclassing an existing FLTK widget, -typically Fl_Widget for controls and Fl_Group for + +\section subclassing_subclassing Subclassing + +New widgets are created by subclassing an existing FLTK widget, +typically Fl_Widget for controls and Fl_Group for composite widgets. -

A control widget typically interacts with the user to receive and/or -display a value of some sort.

-

A composite widget widget holds a list of child widgets and handles moving, -sizing, showing, or hiding them as needed. Fl_Group is the -main composite widget widget class in FLTK, and all of the other composite widgets ( -Fl_Pack, Fl_Scroll, Fl_Tabs, Fl_Tile, -and Fl_Window) are subclasses of it.

-

You can also subclass other existing widgets to provide a different + +A control widget typically interacts with the user to receive and/or +display a value of some sort. + +A composite widget widget holds a list of child widgets and handles moving, +sizing, showing, or hiding them as needed. Fl_Group is the +main composite widget widget class in FLTK, and all of the other composite +widgets (Fl_Pack, Fl_Scroll, Fl_Tabs, +Fl_Tile, and Fl_Window) are subclasses of it. + +You can also subclass other existing widgets to provide a different look or user-interface. For example, the button widgets are all -subclasses of Fl_Button since they all interact with the user +subclasses of Fl_Button since they all interact with the user via a mouse button click. The only difference is the code that draws -the face of the button.

-

Making a Subclass of Fl_Widget

- Your subclasses can directly descend from Fl_Widget or any -subclass of Fl_Widget. Fl_Widget has only four +the face of the button. + +\section subclassing_fl_widget Making a Subclass of Fl_Widget + +Your subclasses can directly descend from Fl_Widget or any +subclass of Fl_Widget. Fl_Widget has only four virtual methods, and overriding some or all of these may be necessary. -

The Constructor

- The constructor should have the following arguments: + +\section subclassing_constructor The Constructor + +The constructor should have the following arguments: + \code MyClass(int x, int y, int w, int h, const char *label = 0); \endcode - This will allow the class to be used in FLUID - without problems. -

The constructor must call the constructor for the base class and -pass the same arguments:

+ +This will allow the class to be used in +FLUID +without problems. + +The constructor must call the constructor for the base class and +pass the same arguments: + \code MyClass::MyClass(int x, int y, int w, int h, const char *label) : Fl_Widget(x, y, w, h, label) { // do initialization stuff... } \endcode -Fl_Widget's protected constructor sets x(), y(), -w(), h(), and label() to the passed values + +Fl_Widget's protected constructor sets x(), y(), +w(), h(), and label() to the passed values and initializes the other instance variables to: + \code type(0); box(FL_NO_BOX); @@ -57,36 +74,47 @@ flags(ACTIVE|VISIBLE); image(0); deimage(0); \endcode -

Protected Methods of Fl_Widget

- The following methods are provided for subclasses to use: - -

void Fl_Widget::damage(uchar mask) -
void Fl_Widget::damage(uchar mask, int x, int y, int w, int h) -
uchar Fl_Widget::damage()

+ +\section subclassing_protected Protected Methods of Fl_Widget + +The following methods are provided for subclasses to use: + +\li Fl_Widget::clear_visible +\li Fl_Widget::damage +\li Fl_Widget::draw_box +\li Fl_Widget::draw_focus +\li Fl_Widget::draw_label +\li Fl_Widget::set_flag +\li Fl_Widget::set_visible +\li Fl_Widget::test_shortcut +\li Fl_Widget::type + + +void Fl_Widget::damage(uchar mask)
+void Fl_Widget::damage(uchar mask, int x, int y, int w, int h)
+uchar Fl_Widget::damage() + +\par The first form indicates that a partial update of the object is -needed. The bits in mask are OR'd into damage(). Your -draw() routine can examine these bits to limit what it is -drawing. The public method Fl_Widget::redraw() simply does - Fl_Widget::damage(FL_DAMAGE_ALL), but the implementation of -your widget can call the private damage(n). -

The second form indicates that a region is damaged. If only these -calls are done in a window (no calls to damage(n)) then FLTK +needed. The bits in mask are OR'd into damage(). Your +draw() routine can examine these bits to limit what it is +drawing. The public method Fl_Widget::redraw() simply does + Fl_Widget::damage(FL_DAMAGE_ALL), but the implementation of +your widget can call the private damage(n). + +\par +The second form indicates that a region is damaged. If only these +calls are done in a window (no calls to damage(n)) then FLTK will clip to the union of all these calls before drawing anything. This can greatly speed up incremental displays. The mask bits are -OR'd into damage() unless this is a Fl_Window widget.

-

The third form returns the bitwise-OR of all damage(n) -calls done since the last draw().

-

When redrawing your widgets you should look at the damage bits to +OR'd into damage() unless this is a Fl_Window widget. + +\par +The third form returns the bitwise-OR of all damage(n) +calls done since the last draw(). + +\par +When redrawing your widgets you should look at the damage bits to see what parts of your widget need redrawing. The handle() method can then set individual damage bits to limit the amount of drawing that needs to be done: @@ -108,90 +136,134 @@ MyClass::draw() { if (damage() & (FL_DAMAGE_ALL | 4)) draw_part3(); } \endcode -

void Fl_Widget::draw_box() const -
void Fl_Widget::draw_box(Fl_Boxtype b, ulong c) const

- The first form draws this widget's box(), using the -dimensions of the widget. The second form uses b as the box -type and c as the color for the box. -

void Fl_Widget::draw_focus() const -
void Fl_Widget::draw_focus(Fl_Boxtype b, int x, int y, int w, int h) const

+ +void Fl_Widget::draw_box() const
+void Fl_Widget::draw_box(Fl_Boxtype b, ulong c) const + +\par +The first form draws this widget's box(), using the +dimensions of the widget. The second form uses b as the box +type and c as the color for the box. -

Draws a focus box inside the widgets bounding box. The second + +void Fl_Widget::draw_focus() const
+void Fl_Widget::draw_focus(Fl_Boxtype b, int x, int y, int w, int h) const + +\par +Draws a focus box inside the widgets bounding box. The second form allows you to specify a different bounding box. -

void Fl_Widget::draw_label() const -
void Fl_Widget::draw_label(int x, int y, int w, int h) const -
void Fl_Widget::draw_label(int x, int y, int w, int h, Fl_Align -align) const

- This is the usual function for a draw() method to call to + +void Fl_Widget::draw_label() const
+void Fl_Widget::draw_label(int x, int y, int w, int h) const
+void Fl_Widget::draw_label(int x, int y, int w, int h, Fl_Align align) const + +\par +This is the usual function for a draw() method to call to draw the widget's label. It does not draw the label if it is supposed to be outside the box (on the assumption that the enclosing group will draw those labels). -

The second form uses the passed bounding box instead of the widget's + +\par +The second form uses the passed bounding box instead of the widget's bounding box. This is useful so "centered" labels are aligned with some -feature, like a moving slider.

-

The third form draws the label anywhere. It acts as though -FL_ALIGN_INSIDE has been forced on so the label will appear inside +feature, like a moving slider. + +\par +The third form draws the label anywhere. It acts as though +FL_ALIGN_INSIDE has been forced on so the label will appear inside the passed bounding box. This is designed for parent groups to draw -labels with.

-

void Fl_Widget::set_flag(SHORTCUT_LABEL)

-Modifies draw_label() so that '&' characters cause an underscore +labels with. + + +void Fl_Widget::set_flag(SHORTCUT_LABEL) + +\par +Modifies draw_label() so that '&' characters cause an underscore to be printed under the next letter. -

void Fl_Widget::set_visible() -
void Fl_Widget::clear_visible()

- Fast inline versions of Fl_Widget::hide() and -Fl_Widget::show(). These do not send the FL_HIDE and -FL_SHOW events to the widget. -

int Fl_Widget::test_shortcut() const -
static int Fl_Widget::test_shortcut(const char *s)

- The first version tests Fl_Widget::label() against the -current event (which should be a FL_SHORTCUT event). If the + + + +void Fl_Widget::set_visible()
+void Fl_Widget::clear_visible() + +\par +Fast inline versions of Fl_Widget::hide() and +Fl_Widget::show(). These do not send the FL_HIDE and +FL_SHOW events to the widget. + + +int Fl_Widget::test_shortcut() const
+static int Fl_Widget::test_shortcut(const char *s) + +\par +The first version tests Fl_Widget::label() against the +current event (which should be a FL_SHORTCUT event). If the label contains a '&' character and the character after it matches the key -press, this returns true. This returns false if the SHORTCUT_LABEL -flag is off, if the label is NULL or does not have a +press, this returns true. This returns false if the SHORTCUT_LABEL +flag is off, if the label is NULL or does not have a '&' character in it, or if the keypress does not match the character. -

The second version lets you do this test against an arbitrary -string.

-

uchar Fl_Widget::type() const -
void Fl_Widget::type(uchar t)

- The property Fl_Widget::type() can return an arbitrary 8-bit -identifier, and can be set with the protected method type(uchar t) -. This value had to be provided for Forms compatibility, but you can + +\par +The second version lets you do this test against an arbitrary string. + + +uchar Fl_Widget::type() const
+void Fl_Widget::type(uchar t) + +\par +The property Fl_Widget::type() can return an arbitrary 8-bit +identifier, and can be set with the protected method type(uchar t). +This value had to be provided for Forms compatibility, but you can use it for any purpose you want. Try to keep the value less than 100 to not interfere with reserved values. -

FLTK does not use RTTI (Run Time Typing Infomation), to enhance + +\par +FLTK does not use RTTI (Run Time Typing Infomation), to enhance portability. But this may change in the near future if RTTI becomes -standard everywhere.

-

If you don't have RTTI you can use the clumsy FLTK mechanisim, by -having type() use a unique value. These unique values must -be greater than the symbol FL_RESERVED_TYPE (which is 100). -Look through the header files for FL_RESERVED_TYPE to find an -unused number. If you make a subclass of Fl_Window -you must use FL_WINDOW + n (n must be in the -range 1 to 7).

-

Handling Events

- The virtual method int Fl_Widget::handle(int event) is called +standard everywhere. + +\par +If you don't have RTTI you can use the clumsy FLTK mechanisim, by +having type() use a unique value. These unique values must +be greater than the symbol FL_RESERVED_TYPE (which is 100). +Look through the header files for FL_RESERVED_TYPE to find an +unused number. If you make a subclass of Fl_Window +you must use FL_WINDOW + n (n must be in the +range 1 to 7). + + +\section subclassing_events Handling Events + +The virtual method int Fl_Widget::handle(int event) is called to handle each event passed to the widget. It can: - - Events are identified by the integer argument. Other information + +\li Change the state of the widget. +\li Call + Fl_Widget::redraw() + if the widget needs to be redisplayed. +\li Call + Fl_Widget::damage(n) + if the widget needs a partial-update (assuming you provide support for + this in your + Fl_Widget::draw() + method). +\li Call + Fl_Widget::do_callback() + if a callback should be generated. +\li Call Fl_Widget::handle() on child widgets. + +Events are identified by the integer argument. Other information about the most recent event is stored in static locations and aquired -by calling the Fl::event_*() - functions. This information remains valid until another event is +by calling the +Fl::event_*() +functions. This information remains valid until another event is handled. -

Here is a sample handle() method for a widget that acts as -a pushbutton and also accepts the keystroke 'x' to cause the callback:

+ +Here is a sample handle() method for a widget that acts as +a pushbutton and also accepts the keystroke 'x' to cause the callback: + \code int MyClass::handle(int event) { switch(event) { @@ -228,52 +300,62 @@ int MyClass::handle(int event) { } \endcode -

You must return non-zero if your handle() method +You must return non-zero if your handle() method uses the event. If you return zero, the parent widget will try sending the event to another widget. -

Drawing the Widget

+ +\section subclassing_drawing Drawing the Widget -

The draw() virtual method is called when FLTK wants +The draw() virtual method is called when FLTK wants you to redraw your widget. It will be called if and only if -damage() is non-zero, and damage() will be -cleared to zero after it returns. The draw() method +damage() is non-zero, and damage() will be +cleared to zero after it returns. The draw() method should be declared protected so that it can't be called from non-drawing code. -

The damage() value contains the bitwise-OR of all -the damage(n) calls to this widget since it was last +The damage() value contains the bitwise-OR of all +the damage(n) calls to this widget since it was last drawn. This can be used for minimal update, by only redrawing the parts whose bits are set. FLTK will turn on the -FL_DAMAGE_ALL bit if it thinks the entire widget must -be redrawn, e.g. for an expose event.

+FL_DAMAGE_ALL bit if it thinks the entire widget must +be redrawn, e.g. for an expose event. -

Expose events (and the above damage(b,x,y,w,h)) will cause -draw() to be called with FLTK's +Expose events (and the above damage(b,x,y,w,h)) will cause +draw() to be called with FLTK's clipping turned on. You can greatly speed up redrawing in some -cases by testing fl_not_clipped(x,y,w,h) or fl_clip_box(...) and -skipping invisible parts.

-

Besides the protected methods described above, FLTK provides a large -number of basic drawing functions, which are described -below.

-

Resizing the Widget

- The resize(int x, int y, int w, int h) method is called when +cases by testing fl_not_clipped(x,y,w,h) or fl_clip_box(...) +and skipping invisible parts. + +Besides the protected methods described above, FLTK provides a large +number of basic drawing functions, which are described +below. + +\section subclassing_resizing Resizing the Widget + +The resize(int x, int y, int w, int h) method is called when the widget is being resized or moved. The arguments are the new -position, width, and height. x(), y(), w(), -and h() still remain the old size. You must call resize() - on your base class with the same arguments to get the widget size to +position, width, and height. x(), y(), w(), +and h() still remain the old size. You must call resize() +on your base class with the same arguments to get the widget size to actually change. -

This should not call redraw(), at least if only the -x() and y() change. This is because composite widgets like -Fl_Scroll may have a more efficient way of drawing the new -position.

-

Making a Composite Widget

- A "composite" widget contains one or more "child" widgets. - To make a composite widget you should subclass Fl_Group -. It is possible to make a composite object that is not a subclass of -Fl_Group, but you'll have to duplicate the code in Fl_Group - anyways. -

Instances of the child widgets may be included in the parent:

+ +This should not call redraw(), at least if only the +x() and y() change. This is because composite widgets like +Fl_Scroll +may have a more efficient way of drawing the new position. + +\section subclassing_composite Making a Composite Widget + +A "composite" widget contains one or more "child" widgets. +To make a composite widget you should subclass +Fl_Group. +It is possible to make a composite object that is not a subclass of +Fl_Group, but you'll have to duplicate the code in Fl_Group +anyways. + +Instances of the child widgets may be included in the parent: + \code class MyClass : public Fl_Group { Fl_Button the_button; @@ -281,9 +363,12 @@ class MyClass : public Fl_Group { ... }; \endcode - The constructor has to initialize these instances. They are automatically - add()ed to the group, since the Fl_Group constructor does Fl_Group::begin(). - Don't forget to call Fl_Group::end() or use the Fl_End pseudo-class: + +The constructor has to initialize these instances. They are automatically +add()ed to the group, since the Fl_Group constructor does +Fl_Group::begin(). +Don't forget to call Fl_Group::end() or use the Fl_End pseudo-class: + \code MyClass::MyClass(int x, int y, int w, int h) : Fl_Group(x, y, w, h), @@ -294,10 +379,12 @@ MyClass::MyClass(int x, int y, int w, int h) : end(); // don't forget to do this! } \endcode - The child widgets need callbacks. These will be called with a pointer -to the children, but the widget itself may be found in the parent() - pointer of the child. Usually these callbacks can be static private + +The child widgets need callbacks. These will be called with a pointer +to the children, but the widget itself may be found in the parent() +pointer of the child. Usually these callbacks can be static private methods, with a matching private method: + \code void MyClass::static_slider_cb(Fl_Widget* v, void *) { // static method ((MyClass*)(v->parent())->slider_cb(); @@ -306,10 +393,12 @@ void MyClass::slider_cb() { // normal method use(the_slider->value()); } \endcode - If you make the handle() method, you can quickly pass all the -events to the children using the Fl_Group::handle() method. -You don't need to override handle() if your composite widget + +If you make the handle() method, you can quickly pass all the +events to the children using the Fl_Group::handle() method. +You don't need to override handle() if your composite widget does nothing other than pass events to the children: + \code int MyClass::handle(int event) { if (Fl_Group::handle(event)) return 1; @@ -317,10 +406,10 @@ int MyClass::handle(int event) { } \endcode -

If you override draw() you need to draw all the -children. If redraw() or damage() is called -on a child, damage(FL_DAMAGE_CHILD) is done to the -group, so this bit of damage() can be used to indicate +If you override draw() you need to draw all the +children. If redraw() or damage() is called +on a child, damage(FL_DAMAGE_CHILD) is done to the +group, so this bit of damage() can be used to indicate that a child needs to be drawn. It is fastest if you avoid drawing anything else in this case: @@ -339,93 +428,99 @@ int MyClass::draw() { } } \endcode -Fl_Group provides some protected methods to make drawing + +Fl_Group provides some protected methods to make drawing easier: -

-

void Fl_Group::draw_child(Fl_Widget&)

- This will force the child's damage() bits all to one and call -draw() on it, then clear the damage(). You should call + +\li draw_child +\li draw_outside_label +\li update_child + + +void Fl_Group::draw_child(Fl_Widget&) + +\par +This will force the child's damage() bits all to one and call +draw() on it, then clear the damage(). You should call this on all children if a total redraw of your widget is requested, or if you draw something (like a background box) that damages the child. - Nothing is done if the child is not visible() or if it is +Nothing is done if the child is not visible() or if it is clipped. -

void -Fl_Group::draw_outside_label(Fl_Widget&) const

- Draw the labels that are not drawn by -draw_label(). If you want more control over the label -positions you might want to call child->draw_label(x,y,w,h,a). -

void Fl_Group::update_child(Fl_Widget&)

- Draws the child only if its damage() is non-zero. You + + +void Fl_Group::draw_outside_label(Fl_Widget&) const + +\par +Draw the labels that are not drawn by +draw_label(). If you want more control over the label +positions you might want to call child->draw_label(x,y,w,h,a). + + +void Fl_Group::update_child(Fl_Widget&) + +\par +Draws the child only if its damage() is non-zero. You should call this on all the children if your own damage is equal to -FL_DAMAGE_CHILD. Nothing is done if the child is not visible() - or if it is clipped. +FL_DAMAGE_CHILD. Nothing is done if the child is not visible() +or if it is clipped. + +\section subclassing_cutnpaste Cut and Paste Support -

Cut and Paste Support

FLTK provides routines to cut and paste 8-bit text (in the future this may be UTF-8) between applications: - -It may be possible to cut/paste non-text data by using -Fl::add_handler(). -

Drag And Drop Support

+\li Fl::paste +\li Fl::selection +\li Fl::selection_owner + +It may be possible to cut/paste non-text data by using +Fl::add_handler(). + +\section subclassing_dragndrop Drag And Drop Support FLTK provides routines to drag and drop 8-bit text between applications: -

Drag'n'drop operations are are initiated by copying data to the +Drag'n'drop operations are are initiated by copying data to the clipboard and calling the function -Fl::dnd(). - -

Drop attempts are handled via events: -

    -
  • FL_DND_ENTER
    • -
  • FL_DND_DRAG
    • -
  • FL_DND_LEAVE
    • -
  • FL_DND_RELEASE
    • -
  • FL_PASTE
    • -
- -

Making a subclass of Fl_Window

- -

You may want your widget to be a subclass of -Fl_Window, Fl_Double_Window, or -FL_Gl_Window. This can be useful if your widget wants +Fl::dnd(). + +Drop attempts are handled via events: + +\li FL_DND_ENTER +\li FL_DND_DRAG +\li FL_DND_LEAVE +\li FL_DND_RELEASE +\li FL_PASTE + +\section subclassing_fl_window Making a subclass of Fl_Window + +You may want your widget to be a subclass of +Fl_Window, Fl_Double_Window, or +FL_Gl_Window. This can be useful if your widget wants to occupy an entire window, and can also be used to take advantage of system-provided clipping, or to work with a library that expects a system window ID to indicate where to draw. -

Subclassing Fl_Windowis almost exactly like -subclassing Fl_Group, and in fact you can easily +Subclassing Fl_Windowis almost exactly like +subclassing Fl_Group, and in fact you can easily switch a subclass back and forth. Watch out for the following -differences:

- -
    - -
  1. Fl_Window is a subclass of - Fl_Group so make sure your constructor calls - end() unless you actually want children - added to your window.
    2. +differences: -
  2. When handling events and drawing, the upper-left - corner is at 0,0, not x(),y() as in other - Fl_Widget's. For instance, to draw a box - around the widget, call draw_box(0, 0, w(), - h()), rather than draw_box(x(), y(), w(), - h()).
    3. +-# Fl_Window is a subclass of Fl_Group so + make sure your constructor calls end() + unless you actually want children added to your window. -
+-# When handling events and drawing, the upper-left corner is at + 0,0, not x(),y() as in other Fl_Widget's. + For instance, to draw a box around the widget, call + draw_box(0, 0, w(), h()), rather than + draw_box(x(), y(), w(), h()). -

You may also want to subclass Fl_Window in order to +You may also want to subclass Fl_Window in order to get access to different visuals or to change other attributes of -the windows. See "Appendix F - Operating -System Issues" for more information. +the windows. See +"Appendix F - Operating System Issues" +for more information.

[Index]    -- cgit v1.2.3