PreviousUpNext

15.3.753  src/lib/x-kit/xclient/src/iccc/window-property.api

## window-property.api
#
# The X server allows X clients to read and write
# arbitrary per-window properties; these properties
# are essentially int-named strings.
#
# In X jargon the name for such a property is an
#
#     atom
#
# It is essentially an integer assigned by the
# X server to compactly represent a string
# registered with it by a client.
#
# Property values are in practice typically ASCII
# strings;  in principle they are arbitrary binary
# data.  The X server pays no attention to property
# contents, serving merely as a blackboard on which
# clients can post them in order to communicate with
# each other.
#
# The X ICCC, "Inter-Client Communication Convention"
# defines a common interclient language based on these
# properties.  It is purely a client convention; the
# X server proper has no knowledge of it.  For more see:
#
#     http://mythryl.org/pub/exene/icccm.pdf
#
# Here we implement a Mythryl interface to getting
# and setting these properties.

# Compiled by:
#     src/lib/x-kit/xclient/xclient-internals.sublib


# Compiled by:
#     src/lib/x-kit/xclient/xclient-internals.sublib



# An interface to the window-property management routines.

stipulate
    include package   threadkit;                                # threadkit             is from   src/lib/src/lib/thread-kit/src/core-thread-kit/threadkit.pkg
    #
    package ts  =  xserver_timestamp;                           # xserver_timestamp     is from   src/lib/x-kit/xclient/src/wire/xserver-timestamp.pkg
#   package ww  =  window;                                      # window                is from   src/lib/x-kit/xclient/src/window/window.pkg
    package sn  =  xsession_junk;                               # xsession_junk         is from   src/lib/x-kit/xclient/src/window/xsession-junk.pkg
herein

    # This api is implemented in:
    #
    #     src/lib/x-kit/xclient/src/iccc/window-property.pkg

    api Window_Property {
                                                                # xtypes                is from   src/lib/x-kit/xclient/src/wire/xtypes.pkg

        Atom;                                                   # xtypes::atom 

        # Raw data from server (in ClientMessage, property values, ...) 

        Raw_Format =    RAW08 | RAW16 | RAW32;

        Raw_Data   =    RAW_DATA
                          {
                            format:  Raw_Format,
                            data:    vector_of_one_byte_unts::Vector
                          };

        # X property values.
        #
        # A property value has a type,
        # which is an atom, and a value.
        #
        # The value is a sequence of
        # 8, 16 or 32-bit items, represented
        # as a format and a bytevector.
        #
        Property_Value
            =
            PROPERTY_VALUE
              {
                type:   Atom,
                value:  Raw_Data
              };

        exception PROPERTY_ALLOCATE;
            #
            # Raised if there is not enough space
            # to store a property value on the server.


        # An abstract interface to a property on a window 
        #
        Property;

        property:  (sn::Window, Atom) -> Property;
            #
            # Return the abstract representation of the
            # named property on the specified window.


        unused_property:  sn::Window -> Property;
            #
            # Generate a property on the specified window
            # that is guaranteed to be unused.
            #
            # Note that once this property has been "deleted"
            # its name may be reused.
            #
            # NOTE: Eventually, properties will be finalized,
            # but for the time being, programs should delete
            # any allocated properties they are not using.


        make_property:  (sn::Window, Property_Value) -> Property;
            #
            # Create a new property initialized to the given value.



        name_of_property:  Property -> Atom;
            #
            # Return the atom that names the given property. 



        set_property:  (Property, Property_Value) -> Void;
            #
            # Set the value of the property. 


        append_to_property:  (Property, Property_Value) -> Void;
            #
            # Append the property value to the property.
            # The types and formats must match.


        prepend_to_property:  (Property, Property_Value) -> Void;
            #
            # Prepend the property value to the property.
            # The types and formats must match.



        delete_property:  Property -> Void;
            #
            # Delete the named property.



        exception ROTATE_PROPERTIES;


        rotate_properties:  (List(Property), Int) -> Void;
            #
            # Rotate the list of properties.
            #
            # Raises ROTATE_PROPERTIES if the
            # properties do not belong to the
            # same window.



        get_property:  Property -> Null_Or( Property_Value );
            #
            # Get the value of the property.
            #
            # Return NULL if the property has
            # not been set.



        Property_Change = NEW_VALUE | DELETED;


        watch_property:  (Property, (Property_Change, ts::Xserver_Timestamp) -> Void) -> Void;
            #
            # Changed from the below to registering a watcher function.   -- 2013-08-11 CrT
            #
            # Return a mailop for monitoring
            # changes to a property's state.
            #
            # Note that once a property has
            # been deleted, there will be no
            # more events unless watch_property
            # is called again.




        xrdb_of_screen:     sn::Screen -> List( String );
            #   
            # xrdb_of_screen: Return the list of strings contained in the
            # XA_RESOURCE_MANAGER property of the root screen of the
            # specified screen. 
            # This should properly belong some other place than in ICCC,
            # as it has nothing to do with ICCC, except that it accesses
            # data in the screen type, and uses the GetProperty functions
            # of ICCC.          XXX BUGGO FIXME
    };

end;


## COPYRIGHT (c) 1994 by AT&T Bell Laboratories.  See SMLNJ-COPYRIGHT file for details.
## Subsequent changes by Jeff Prothero Copyright (c) 2010-2015,
## released per terms of SMLNJ-COPYRIGHT.


Comments and suggestions to: bugs@mythryl.org

PreviousUpNext