[Gzz] fourth PEG cursors--humppake: Changing mouse cursor

[Asko Soukka]

==========================================================================
PEG cursors--humppake: Changing mouse cursor
==========================================================================

:Authors:  Asko Soukka
:Date-Created: 2003-05-09
:Last-Modified: $Date: 2003/05/09 13:36:51 $
:Revision: $Revision: 1.7 $
:Status:   Current
:Scope:    Trivial
:Type:     Feature, Interface, Implementation

.. :Stakeholders:
.. :Type:     META|Policy|Architecture|Interface|Implementation

.. Affect-PEGs:

This peg describes, how changing of mouse cursor to any of the default
system cursors could be easily implemented on LibVob.

Issues
======

.. - Do we want to change mouse cursor?

        RESOLVED: Yes, we do. OF course, different effective areas on
        GUI should be noticeable also without changing mouse cursor on
        top of them, but mouse different cursors would work as
        additional visual glues. Except for the effective ares, also
        for the overall application state.

- How the mouse cursor should be changed?

        RESOLVED: Calling 
``org.nongnu.libvob.GraphicsAPI.Window.setCursor()``
        with ID of wanted cursor as a parameter. Of course setCursor() 
method
        should be implemented separately for both AWT and GL.

        RE-RESOLVED: Calling 
``org.nongnu.libvob.GraphicsAPI.Window.setCursor()``
        with java.awt.Cursor as parameter.

        RE-RESOLVED: Calling 
``org.nongnu.libvob.GraphicsAPI.Window.setCursor()``
        with proper cursor name string as parameter.

        AWTAPI will also have setCursor() overloaded with java.awt.Cursor 
        as parameter..

- How is changing the mouse cursor implemented?
        
        RESOLVED: Java AWT client uses ``java.awt.Cursor``, which can
        be passed to any ``java.awt.Component`` - like ScreenCanvas in
        AWTScreen. GL client needs a platform specific implementation.
        Currently we are supporting X implementation. In X Windows,
        mouse cursor could be changed via Xlib.

- How cursor name string is mapped to Xlib mouse cursor values?

        RE-RESOLVED: Cursor name string is passed on in
        ``org.nongnu.libvob.impl.gl.GLScreen`` and
        low level implementation like using Xlib is determined later
        on. Most probably in /src/os/Os-GLX.

- How cursor name string is mapped to AWT mouse cursor values?

        RE-RESOLVED: Cursor name string is converted to
        corresponding ``java.awt.Cursor``, which is passed
        to proper AWT component. 

- What is the available set of mouse cursors?
        
        RESOLVED: The set of available mouse cursors is the intersection 
of
        Xlib and AWT mouse cursors sets:

        - 
http://java.sun.com/products/jdk/1.2/docs/api/java/awt/Cursor.html
        - http://tronche.com/gui/x/xlib/appendix/b/

        RE-RESOLVED: To be more specific, all Java AWT cursors except 
        custom cursor are available.

        RE-RESOLVED: A stable sub set of available cursor should be 
        defined in Graphics API. At start, it will be the same as Java AWT
        cursors except the custom cursor. AWT and GL cursor APIs can
        then be extended (also separately).

- Should we use our own custom cursors?

        RESOLVED: Not yet. Probably we would like to use also our own
        custom cursors in the future, but at first it is more relevant
        to get at least changing of default system cursors work.

        NOTE: In Java, Toolkit.createCustomCursor is available since
        JDK 1.2. How custom cursor could be used efficiently in GL?

        RE-RESOLVED: Since ustom cursors should be also possible 
        outside the AWT, using custom cursor is allowed. Althought, left
        yet unimplemented in GL.

        RE-RESOLVED: General GraphicsAPI won't contain custom cursor
        choice, but custom cursor can be added into GL and AWT APIs 
        later on. If some cursor is implemented to them both, it can
        be included into general GraphicsAPI.

- How java.awt.Cursor is mapped to Xlib mouse cursor values?

        RESOLVED: Mapping is done in setCursor() method
        in ``org.nongnu.libvob.impl.gl.GLScreen`` using switch structure.

        RE-RESOLVED: String value corresponding to cursor is 
        passed to on in ``org.nongnu.libvob.impl.gl.GLScreen`` and
        low level implementation like usin Xlib is determined later on.
        At first in /src/os/Os-GLX.

        RE-RESOLVED: Irrelevant.

- What are the mouse cursor IDs?
        
        RESOLVED: IDs are our own constants mapped to integer values that
        correspond the mouse cursors in current environment. Integers 
        for specific mouse cursors are different in AWT and Xlib and 
that's
        why we need our own mapping for them.

        RE-RESOLVED: Irrelevant.

- Where are the mouse cursor ID mappings located?
        
        RESOLVED: Mouse cursor constants are described with AWT values as 
default
        in ``org.nongnu.libvob.GraphicsAPI``. For GL implementation those
        mappings must be overwritten into
        ``org.nongnu.libvob.impl.gl.GLAPI``.

        RE-RESOLVED: Irrelevant.

- Since it's possible to call setCursor() with pure integer values, is
  it allowed to use AWT or Xlib specific cursors?

        RESOLVED: Yes, but with care. If the application is runnable under
        both AWT and GL, there should be checking for proper GraphicsAPI..


        RESOLVED: Irrelevant. Not possible anymore.

Changes
=======

Interfaces
----------

Into ``org.nongnu.libvob.GraphicsAPI.Window``::

    /** Set the mouse cursor for the window.
     * Available cursor types  (case insensitive):
     * "CROSSHAIR_CURSOR"  The crosshair cursor type.
     * "DEFAULT_CURSOR" The default cursor type (gets set if no cursor is 
defined).
     * "E_RESIZE_CURSOR" The east-resize cursor type.
     * "HAND_CURSOR" The hand cursor type.
     * "MOVE_CURSOR" The move cursor type.
     * "N_RESIZE_CURSOR" The north-resize cursor type.
     * "NE_RESIZE_CURSOR" The north-east-resize cursor type.
     * "NW_RESIZE_CURSOR" The north-west-resize cursor type.
     * "S_RESIZE_CURSOR" The south-resize cursor type.
     * "SE_RESIZE_CURSOR" The south-east-resize cursor type.
     * "SW_RESIZE_CURSOR" The south-west-resize cursor type.
     * "TEXT_CURSOR" The text cursor type.
     * "W_RESIZE_CURSOR" The west-resize cursor type.
     * "WAIT_CURSOR" The wait cursor type.
     */
    public void setCursor(String shape);

Into ``org.nongnu.libvob.impl.awt.AWTScreen``::
 
    /** Set the mouse cursor for the window.
     */ 
    public void setCursor(Cursor cursor) {
        canvas.setCursor(cursor);
    }



Implementation
--------------

Java
""""

Into ``org.nongnu.libvob.impl.awt.AWTScreen``::
 
    public void setCursor(String cursorName) {
        Cursor cursor = null;
        if (cursorName == "CROSSHAIR_CURSOR")
          cursor = new Cursor(Cursor.CROSSHAIR_CURSOR);
        else if (cursorName == "DEFAULT_CURSOR")
          cursor = new Cursor(Cursor.DEFAULT_CURSOR);
        else if (cursorName == "E_RESIZE_CURSOR")
          cursor = new Cursor(Cursor.E_RESIZE_CURSOR);
        else if (cursorName == "HAND_CURSOR")
          cursor = new Cursor(Cursor.HAND_CURSOR);
        else if (cursorName == "MOVE_CURSOR")
          cursor = new Cursor(Cursor.MOVE_CURSOR);
        else if (cursorName == "N_RESIZE_CURSOR")
          cursor = new Cursor(Cursor.N_RESIZE_CURSOR);
        else if (cursorName == "NE_RESIZE_CURSOR")
          cursor = new Cursor(Cursor.NE_RESIZE_CURSOR);
        else if (cursorName == "NW_RESIZE_CURSOR")
          cursor = new Cursor(Cursor.NW_RESIZE_CURSOR);
        else if (cursorName == "S_RESIZE_CURSOR")
          cursor = new Cursor(Cursor.S_RESIZE_CURSOR);
        else if (cursorName == "SE_RESIZE_CURSOR")
          cursor = new Cursor(Cursor.SE_RESIZE_CURSOR);
        else if (cursorName == "SW_RESIZE_CURSOR")
          cursor = new Cursor(Cursor.SW_RESIZE_CURSOR);
        else if (cursorName == "TEXT_CURSOR")
          cursor = new Cursor(Cursor.TEXT_CURSOR);
        else if (cursorName == "W_RESIZE_CURSOR")
          cursor = new Cursor(Cursor.W_RESIZE_CURSOR);
        else if (cursorName == "WAIT_CURSOR")
          cursor = new Cursor(Cursor.WAIT_CURSOR);
        else throw new IllegalArgumentException("Unknown cursor: 
"+cursorName);
        canvas.setCursor(cursor);
    }

Into ``org.nongnu.libvob.gl.GL.Window``::

    /** Set the mouse cursor of the window.
     */
    public void setCursor(String cursorName) { 
impl_Window_setCursor(getId(), cursorName); }

Into ``org.nongnu.libvob.gl.GL``::

    static private native void impl_Window_setCursor(int id, String 
cursorName);

Into ``org.nongnu.libvob.impl.GL.GLScreen``::

    public void setCursor(String cursorName) {
      if (cursorName == "CROSSHAIR_CURSOR" ||
          cursorName == "DEFAULT_CURSOR" ||
          cursorName == "E_RESIZE_CURSOR" ||
          cursorName == "HAND_CURSOR" ||
          cursorName == "MOVE_CURSOR" ||
          cursorName == "N_RESIZE_CURSOR" ||
          cursorName == "NE_RESIZE_CURSOR" ||
          cursorName == "NW_RESIZE_CURSOR" ||
          cursorName == "S_RESIZE_CURSOR" ||
          cursorName == "SE_RESIZE_CURSOR" ||
          cursorName == "SW_RESIZE_CURSOR" ||
          cursorName == "TEXT_CURSOR" ||
          cursorName == "W_RESIZE_CURSOR" ||
          cursorName == "WAIT_CURSOR")
            window.setCursor(cursorName);
      else throw new IllegalArgumentException("Unknown cursor: 
"+cursorName);
    }

C
"

Into ``include/vob/os/Os.cxx Vob.Os.Window``::

    virtual void setCursor(const std::string cursorName) = 0;

Into ``src/jni/Main.cxx``::

    jf(void, impl_1Window_1setCursor)
    (JNIEnv *env, jclass, jint id, jstring cursorName) {
          Os::Window *w = (Os::Window *)windows.get(id);
          DBG(dbg) << "Set window "<<id<<" Cursor cursorName 
"<<cursorName<<" at "<<(int)w<<"\n";
          std::string cCursorName_str = jstr2stdstr(env, cursorName);
          w->setCursor(cCursorName_str);
    }

Into ``src/os/Os-GLX.cxx``::

    // For setCursor()
    #include <X11/Xlib.h>
    #include <X11/cursorfont.h>
    //

Into ``src/os/Os-GLX.cxx Vob.Os.LXWindow``::

    virtual void setCursor(const std::string cursorName) {
        Cursor cursor = 0;
        if (cursorName == "CROSSHAIR_CURSOR")
          cursor = XCreateFontCursor(ws->dpy, XC_crosshair);
        else if (cursorName == "DEFAULT_CURSOR")
          cursor = XCreateFontCursor(ws->dpy, XC_left_ptr);
        else if (cursorName == "E_RESIZE_CURSOR")
          cursor = XCreateFontCursor(ws->dpy, XC_right_side);
        else if (cursorName == "HAND_CURSOR")
          cursor = XCreateFontCursor(ws->dpy, XC_hand2);
        else if (cursorName == "MOVE_CURSOR")
          cursor = XCreateFontCursor(ws->dpy, XC_fleur);
        else if (cursorName == "N_RESIZE_CURSOR")
          cursor = XCreateFontCursor(ws->dpy, XC_top_side);
        else if (cursorName == "NE_RESIZE_CURSOR")
          cursor = XCreateFontCursor(ws->dpy, XC_top_right_corner);
        else if (cursorName == "NW_RESIZE_CURSOR")
          cursor = XCreateFontCursor(ws->dpy, XC_top_left_corner);
        else if (cursorName == "S_RESIZE_CURSOR")
          cursor = XCreateFontCursor(ws->dpy, XC_bottom_side);
        else if (cursorName == "SE_RESIZE_CURSOR")
          cursor = XCreateFontCursor(ws->dpy, XC_bottom_right_corner);
        else if (cursorName == "SW_RESIZE_CURSOR")
          cursor = XCreateFontCursor(ws->dpy, XC_bottom_left_corner);
        else if (cursorName == "TEXT_CURSOR")
          cursor = XCreateFontCursor(ws->dpy, XC_xterm);
        else if (cursorName == "W_RESIZE_CURSOR")
          cursor = XCreateFontCursor(ws->dpy, XC_left_side);
        else if (cursorName == "WAIT_CURSOR")
          cursor = XCreateFontCursor(ws->dpy, XC_watch);
        if (cursor != 0) XDefineCursor(ws->dpy, xw, cursor);
    } 
 

-- 
Asko Soukka <address@hidden>
<http://www.iki.fi/asko.soukka/>