[Gzz] Fixed 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 10:48:06 $
:Revision: $Revision: 1.3 $
: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. Different effective ares on
        GUI should be noticeable also without changing mouse cursor on
        top of them, of course, mouse cursors would work as
        additional visual glues. Except for the effective ares, also
        for the 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.

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

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

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

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

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

Changes
=======

Java
----

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

    /** Sets the mouse cursors shape.
     */
    void setCursor(Cursor cursor);

Into ``org.nongnu.libvob.impl.awt.AWTScreen``::
 
    public void setCursor(cursor Cursor) {
       canvas.setCursor(cursor);
    }

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

    static private native void impl_Window_setCursor(int id, int shape);

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

    /** Changes mouse cursor on the window.
     */
    public void setCursor(int shape) { impl_Window_setCursor(getId(), 
shape); }

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

    public void setCursor(Cursor cursor) {
        switch cursor {
            case Cursor.CROSSHAIR_CURSOR: window.setCursor(130); break;  
// XC_tcross
            case Cursor.DEFAULT_CURSOR: window.setCursor(68); break; // 
XC_left_ptr
            case Cursor.E_RESIZE_CURSOR: window.setCursor(98); break; // 
XC_righside
            case Cursor.HAND_CURSOR: window.setCursor(60); break; // 
XC_hand2
            case Cursor.MOVE_CURSOR: window.setCursor(52); break; // 
XC_fleur
            case Cursor.N_RESIZE_CURSOR: window.setCursor(138); break; // 
XC_top_side
            case Cursor.NE_RESIZE_CURSOR: window.setCursor(136); break; // 
XC_top_right_corner
            case Cursor.NW_RESIZE_CURSOR: window.setCursor(134); break; // 
XC_top_left_corner
            case Cursor.S_RESIZE_CURSOR: window.setCursor(16); break; // 
XC_bottom_side
            case Cursor.SE_RESIZE_CURSOR: window.setCursor(14); break; // 
XC_bottom_right_corner
            case Cursor.SW_RESIZE_CURSOR: window.setCursor(12); break; // 
XC_bottom_left_corner
            case Cursor.TEXT_CURSOR: window.setCursor(152); break; // 
XC_xterm
            case Cursor.W_RESIZE_CURSOR: window.setCursor(70); break; // 
XC_left_side
            case Cursor.WAIT_CURSOR: window.setCursor(150); break; // 
XC_watch
        }
    }

C
-

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

    virtual void setCursor(int shape) = 0;

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

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

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

    #include <X11/Xlib.h>

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

    virtual void setCursor(int shape) {
       XDefineCursor(ws->dpy, xw, XCreateFontCursor(ws->dpy, shape));
    }
 



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