| home | support |contact | forum | ||||||||||||||||||||||||||||||||||||
| Zhorn Software | ||||||||||||||||||||||||||||||||||||
|
API Commands
Text in <angle brackets> is a parameter - in a command, it will need to be filled in when the command is sent. In a return value, it will change according to the current state of Stickies. There are very many commands and events which Stickies could respond to, and send. The set below is quite incomplete. Adding a new command to the API is a simple task, but rather than code in potentially several hundred routine, most of which will never get used, instead if your application needs something which is not here, let me know, I can add it, and get an updated executable to you for development.
do ping Check a connection to Stickies Return values
000 pong Remarks Check that you are able to send commands to, and receive a reply from Stickies. This command will have no other effect on Stickies. If the client has successfully registered for events with Stickies, then the second return string will be recieved. Otherwise it will be the former.
do new sticky <text> Create a new sticky, with the default style Return values
000 OK created: <id> Remarks With no content specified, a new blank sticky is created. Otherwise, the sticky will have the contents specified at the end of the command. The sticky id is supplied in the reply, so that additional attributes can be set if required.
do desktop <id> close Requires: 6.7a Closes the specified desktop sticky Return values
000 OK closed Remarks Removes the sticky from the desktop, and places it in the Closed category, so that the user is able to restore it if they choose.
do desktop <id> delete Requires: 6.7a Permanently removes the specified desktop sticky Return values
000 OK deleted Remarks The sticky is completely removed, and is not added to the Closed category
do manage open Open the Manage dialog Return values
000 opened Remarks Open the Manage dialog
do manage close Close the manage dialog Return values
000 closed Remarks Close the manage dialog
do stickymenuadd <command> <menu text> Add an item to the right-click menu of each sticky which generates an API event when clicked Return values
000 added Remarks Create a hook back to your code from a sticky with this command. The menu text you supply will be added as an item to the bottom of each sticky menu, and when the user selects that menu item, an event with the code "command" as specified here is sent to all API clients which have registered for events. The command has the identifier of the sticky for which the user caused the menu to show in it. If the command specified already exists as a menu in Stickies, no changes are made, and the error is returned.
do stickymenudel <command> Remove an item previously added to the right-click menu of each sticky Return values
000 removed Remarks Removes a menu command previously added by the "do stickymenuadd" command. As the item has then been removed, it can no longer be clicked by the user, so no more events with the specified code will be received.
do stickiesmenuadd <command> <menu text> Add an item to the task-tray menu of Stickies which generates an API event when clicked Return values
000 added Remarks Create a hook back to your code from Stickies with this command. The menu text you supply will be added as an item to the main Stickies menu, and when the user selects that menu item, an event with the code "command" as specified here is sent to all API clients which have registered for events. If the command specified already exists as a menu in Stickies, no changes are made, and the error is returned.
do stickiesmenudel <command> Remove an item previously added to the task-tray menu of Stickies Return values
000 removed Remarks Removes a menu command previously added by the "do stickiesmenuadd" command. As the item has then been removed, it can no longer be clicked by the user, so no more events with the specified code will be received.
do register Request notification of events within Stickies Return values
000 will send events your way Remarks The command adds the calling application to the list of windows to which Stickies will send a notification when an event within Stickies occurs. A list of events can be found here. The calling application must fill in the window handle parameter of the SendMessage Windows API call, so that Stickies can send events to that window when they occur. If at any point Stickies tries to send a message to your application and fails, then it will be removed from its list of API clients.
do deregister Cease sending of events Return values
000 no more events will be sent Remarks No more events will be sent from Stickies to your application. Making this call as your application exits is neat, but not essential, as Stickies will stop trying to send events once it's tried to do so once and failed.
do hideall Requires: 7.0a Hide all desktop stickies from view Return values
000 hidden Remarks All desktop stickies are hidden, and the tray icon changes to indicate that this is the case
do showall Requires: 7.0a Show all desktop stickies following them being hidden Return values
000 shown Remarks All desktop stickies are shown again, and the tray icon changes back to normal.
do desktop <id> rolled Requires: 7.0a Set the specified desktop sticky rolled up. Return values
000 rolled Remarks If the skin does not support being rolled up, the error will be returned
do desktop <id> unrolled Requires: 7.0a Set the specified desktop sticky unrolled. Return values
000 unrolled Remarks Ensures that the specified sticky is not rolled up
do backup <path> Requires: 7.0a Performs a backup of all Stickies data to the specified path Return values
000 backup taken Remarks Creates the destination directory if it does not exist, and then copies all live data into that location. Any files which are already in that location with the same name will be overwritten without prompting
do sleep <id> <waketime> <options> Requires: 7.0a Send the specified sticky to sleep Return values
000 slept Remarks Moves a desktop sticky to the sleeping list, to wake at the specified time, which is in seconds since midnight, Jan 1st 1970 UTC. For example, 02:00 on the 12th November 2009 will be 1257991200. Options is three characters, each is 0 or 1, which refer to "make sound", "on top" and "trigger alarm", eg specify "111" to do all three, or "010" to make no noise, but be on top
do recurr <id> <firstwake> <type> <hours> <minutes> <days> <lastwake> <options> Requires: 7.0a Set the specified sticky to recurr Return values
000 slept Remarks Moves a desktop sticky to the sleeping list, to wake repeatedly from the firstwake to the lastwake, according to the schedule:
The <options> are the same as for the "do sleep" command detailed above
do wake <id> Requires: 7.0a Wakes the specified sticky Return values
000 woken Remarks Move a sleeping or recurring sticky to the desktop. Recurring stickies will no longer recurr once woken with this command
do new sleeping <encoded> Requires: 7.0a Creates a new sleeping sticky from the encoded string Return values
000 created: <id> Remarks Create a new sleeping sticky from the encoded string. This must be correctly formatted, see the return from the "get sleeping <id> encoded" command for this
do bringforward Requires: 7.0a Brings all stickies to the top of the z-order Return values
000 done Remarks This performs the same action as single-clicking the tray icon
do alarmstart <id> Requires: 7.0a Starts the alarm on the specified sticky Return values
000 alarmed Remarks The sticky will start to flash / jiggle / sound as per the user's specification in the Options dialog
do alarmstop <id> Requires: 7.0a Stops the alarm on the specified sticky Return values
000 quieted Remarks The specified sticky will no longer be alarming
do findhandle <handle> Requires: 7.0a Identify a desktop sticky from its window handle Return values
001 <id> Remarks Searches the current Desktop stickies for one which has the specified window handle, and returns the id of the sticky. The window handle must be a decimal number, and is the return value from API commands such as ::FindWindow()
do getnewfriends Requires: 7.0a Sync with server and add any new friends found to the Friend list Return values
000 done Remarks Does the same as clicking the "Get New Friends" button, and adds new Friends to a new group at the bottom of the Friend list
set skin <pathname> Set the Stickies skin to be the file specified Return values
000 set Remarks The Stickies skin is set to the pathname in the command, and all stickies are refreshed with the new look. The skin can be either an ini file, or a ssk. A failure will mean the default skin is loaded, and the 997 error message returned.
get skin Get the loaded Stickies skin file Return values
001 <skinfile_path> Remarks Return the path to the currently loaded skin. If this is blank, then the default skin is loaded.
get version Get the version of Stickies which is running Return values
001 <version> Remarks Return the Stickies version, in the format "Stickies vX.XX"
get datapath Requires: 6.7a Get the path Stickies is currently using for data storage Return values
001 <path> Remarks This permits access to the path which is displayed at the bottom of the About dialog in Stickies. This location is where Stickies stores all data files, and also the log file if one is being written.
get desktop <id> title Get the title of the specified desktop sticky Return values
001 <current title> Remarks Return the title of the specified desktop sticky. The return value is converted to ANSI and so unicode characters will not be correct.
get desktop <id> source Get the source of the specified desktop sticky Return values
001 <current source> Remarks Return the source of the specified desktop sticky
get desktop <id> colour Get the colour of the specified desktop sticky Return values
001 <red,green,blue> Remarks Return the colour of the specified desktop sticky. The returned string is three comma-separated numbers which give the red, green and blue values.
get desktop <id> text Get the contents of the specified desktop sticky Return values
001 <text> Remarks Return the text of the specified desktop sticky. The returned string is plain text, and contains no formatting
get desktop <id> position Get the screen location of the specified desktop sticky Return values
001 <x,y> Remarks Return the location in virtual screen co-ordinates of the specified desktop sticky. This means that one or both of the values may be negative.
get desktop <id> size Get the dimensions of the specified desktop sticky Return values
001 231x89 Remarks Return the size in pixels of the specified desktop sticky. If the sticky is rolled, the current height of the just the title bar is returned, not the full height when the sticky is unrolled.
get desktop <id> ontop Requires: 6.7a Get the always-on-top status of the specified desktop sticky Return values
001 0 Remarks If the sticky is on-top, then the value 1 is returned, otherwise 0.
get desktop <id> userstring1 Requires: 6.7a Get the value of the 'userstring1' attribute of the specified desktop sticky Return values
001 <value> Remarks The 'userstring1' value is not used by Stickies in any way, and is provided for third party extentions
get desktop <id> hidden Requires: 6.7a Returns whether the specified desktop sticky is hidden from view Return values
001 0 Remarks The return value 0 means the sticky is visible on screen. The return value 1 means the sticky is currently hidden from view.
get desktop <id> ghost Requires: 6.7a Returns whether the specified desktop sticky has 'ghost' mode enabled Return values
001 0 Remarks The return value 0 means the sticky is 'normal'. The return value 1 means the sticky cannot be interacted with by the mouse, although it is visible.
get desktop <id> transparency Requires: 6.7a Returns the transparency value of the specified desktop sticky Return values
001 <value> Remarks The value is a percentage, between 0 and 100. Either 0 or 100 means the sticky is opaque. Lower percentages mean the sticky is more transparent.
get desktop <id> modified Requires: 6.7a Returns the last modification date of the specified desktop sticky Return values
001 <time> <year> <month> <day> <hours> <minutes> <seconds> <dayofweek> Remarks The first of the values returned, time, is the number of seconds since Jan 01, 1970, and as such can be used to specify a unique point in time, and be used for relative calculations. Add 3600 to the value to get the time an hour later. However, be wary of daylight savings time, leap years and time zones if using this value. The remaining values are provided for convenience and can be reformatted for display. The day of week counts from Sunday, so Sunday = 1, Monday = 2 ... Saturday = 7. The modified value is updated when these attributes of a sticky are altered:
get desktop <id> encoded Requires: 6.7a Returns an encoded string containing all elements of the sticky Return values
001 <encoded string> Remarks The format of the string is the same as is saved to the ini file. For more details on the format, see the "stickies.ini" section of the Stickies help file. e.g.
<X>0736<Y>0930<WIDTH>352<HEIGHT>60<ONTOP>0<ID>2114B9845C820C5
get desktop <id> type Requires: 7.0a Returns an integer describing the type of sticky, rtf or text Return values
001 0 Remarks 0 is a RTF (text) sticky, 1 is an image sticky
get desktop <id> handle Requires: 7.0a Returns the Windows handle to the specified sticky Return values
001 <handle> Remarks The return value is a decimal integer, and can be used in Windows API commands such as ::SetWindowPos()
get desktop <id> rolled Requires: 7.0a Returns whether the specified Desktop sticky is rolled up Return values
001 0 Remarks 0 is not rolled up. 1 is rolled up.
get desktop <id> skinpath Requires: 7.0a Returns the skin file the sticky is using Return values
001 <path_to_file> Remarks If the specified sticky is using a custom skin, the path to the file is returned. Otherwise, if the sticky is instead using the default skin, the text <default> is returned.
get desktop <id> utitle Requires: 7.0a Return the unicode-formatted title of the specified sticky Return values
001 <encoded_unicode> Remarks The return value is an 8-bit string, so in order to correctly store unicode characters, an encoding scheme is used which uses four hex characters for each one unicode character. In order to convert from the encoded string, take each set of four characters in turn, and that's the number of the unicode character. Similarly, to generate an encoded string, convert each unicode character in turn to a hex value, and then store those in sequence.
The title "Stickies" has an encoded utitle of: 0053007400690063006B006900650073
get sleeping <id> encoded Requires: 7.0a Returns an encoded string containing all elements of the sleeping or recurring sticky Return values
001 <encoded> Remarks The format of the string is the same as is saved to the ini file. For more details on the format, see the "stickies.ini" section of the Stickies help file.
get sleeping <id> position Requires: 7.0a Return the the on-screen position a woken sticky will have Return values
001 <x,y> Remarks When a sleeping sticky wakes, it will appear at a saved position on the screen. This command will return that position.
set desktop <id> title <title> Set the title of the specified desktop sticky Return values
000 title set Remarks Set the title of the specified desktop sticky. To clear the title, send the command with a space after the word title, eg:
"set desktop 20EFA3490AF2 title "
set desktop <id> source <source> Set the source of the specified desktop sticky Return values
000 source set Remarks Set the source of the specified desktop sticky
set desktop <id> colour <red,green,blue> Set the colour of the specified desktop sticky Return values
000 colour set Remarks Set the colour of the specified desktop sticky. The colour should be in the format red,green,blue
set desktop <id> text <text> Set the contents of the specified desktop sticky Return values
000 text set Remarks Set the contents of the specified desktop sticky. The input is plain text.
set desktop <id> position <x,y> Set the position on screen of the specified desktop sticky Return values
000 position set Remarks Set the location in virtual screen co-ordinates of the specified desktop sticky. This means that one or both of the values may be negative.
set desktop <id> ontop <0|1> Requires: 6.7a Set the always-on-top status of the specified desktop sticky Return values
000 ontop set Remarks Set the on-top status of the specified sticky. Pass 0 as the parameter to remove on-top, and pass 1 to set it.
set desktop <id> userstring1 <value> Requires: 6.7a Set the 'userstring1' value of the specified desktop sticky Return values
000 userstring1 set Remarks Sets the specified string parameter as the value of the sticky 'userstring1' value. This value has no relevance to Stickies, but is stored and transmitted over the network. It is provided for third party extentions.
set desktop <id> hidden <0|1> Requires: 6.7a Hides or reveals the specified desktop sticky Return values
000 hidden set Remarks Hidden desktop stickies are just that - they do not appear on the screen although they do appear in a list of desktop stickies. In the Manage dialog, a pair of dark glasses on the icon shows that the sticky has this setting. They cannot be edited, moved or interacted with in any way by the user while hidden.
set desktop <id> ghost <0|1> Requires: 6.7a Sets the specified desktop sticky as non-clickable Return values
000 ghost set Remarks Stickies with 'ghost' mode cannot be clicked on. They appear on the desktop along with all other stickies, and if focus is transferred to one (by control-tabbing to it, or double-clicking it in the Desktop cateogry of the Manage dialog) then it can be used as usual, but no mouse events will be received by it, and instead will "pass though" to whichever window is underneath the sticky in z-order.
set desktop <id> transparency <0-100> Requires: 6.7a Sets the transparency level of the specified desktop sticky Return values
000 transparency set Remarks The value is a percentage - either 0 or 100 will make the sticky completely opaque. 1 is extremely faint, and 99 is only very slightly transparent. Values outside the range 0-100 will be interpreted as opaque.
set desktop <id> style <0-9> Requires: 6.7a Sets the style of the specified desktop sticky Return values
000 style set Remarks Sets the specified desktop sticky to the style. If the style specified does not exist, the 997 error is returned.
set desktop <id> utitle <utitle> Requires: 7.0a Sets the unicode-formatted title of the specified sticky Return values
000 title set Remarks The <utitle> parameter must be a string formatted in groups of four hex characters - see the remarks for the "get desktop utitle" command for more details on how this should be formatted.
set desktop <id> image <path> Requires: 7.0a Converts the specified sticky to an image sticky, and loads the file specified Return values
000 image set Remarks If the sticky is a RTF one, any text it contains will be discarded. If it is an image one, the current image will be overwritten.
set desktop <id> rtf <rtf> Requires: 7.0a Sets the formatted text of a Desktop RTF sticky Return values
000 rtf set Remarks If the sticky is an image sticky, the command will fail. Otherwise, the RTF contents will be set.
set desktop <id> id <newid> Requires: 7.0a Sets the id of a sticky Return values
000 id set Remarks Changes the unique id of a desktop sticky. Once this command has executed, use the new value to send it any further commands. No error checking is performed - if the id already exists, a duplicate will be created, and further commands which reference the duplicate id may have unpredictable results.
set desktop <id> modified <time> Requires: 7.0a Sets the last modified time of a sticky Return values
000 modified set Remarks Sets the last modified time of a Desktop sticky to an absolute point in time.
set desktop <id> skinpath <path> Requires: 7.0a Sets the skin the one specified Desktop sticky uses Return values
000 skin set Remarks Alters the skin which the specified sticky uses. The <path> parameter can be either the path to a .ssk or .ini file, or the value <default> which will set the sticky skin back to the user's current default.
set sleeping <id> waketime <time> Requires: 7.0a Alter the wake time of a sleeping sticky Return values
000 wake time set Remarks The <time> parameter has two formats - either an absolute point in time (eg 1243801800), or a relative one (eg +3600). The absolute value sets the wake time to be that point in time. The value which starts with the + sets it to be now plus the number of seconds. So, setting +3600 at 16:38 on a day will mean the sticky will wake at 17:38 on that day.
set sleeping <id> position <x,y> Requires: 7.0a Sets the woken screen position of a sleeping sticky Return values
000 position set Remarks Sleeping stickies have no screen position as they are not visible on the screen. However, they store a screen position for whem they wake up. This command alters that saved screen position without waking the sticky.
get list desktop Get a list of unique ids of the stickies currently active on the desktop Return values
001 <id,id,id...> Remarks The id of each desktop sticky is separated by a comma. The list is terminated with a comma. Desktop stickies are those which appear in the Desktop category in the Manage dialog.
get list sleeping Get a list of unique ids of the stickies currently sleeping and recurring Return values
001 <id,id,id...> Remarks The id of each desktop sticky is separated by a comma. The list is terminated with a comma.
get ipfromfriend <friendname> Get a friend's IP address/hostname Return values
001 <address> Remarks Get the value of the Address: field for the specified friend. The matching is case-insensitive. If the friend cannot be found, then the friend name supplied is returned.
get friendfromip <address> Get a friend name from their IP address/hostname Return values
001 <friendname> Remarks Get the friend name of the friend which matches the specified address. The matching is case-insensitive. If a friend cannot be found, then the address supplied is returned.
get datapath Requires: 7.0a Get the path to the directory which Stickies is using to store its data Return values
001 <path> Remarks This is the same path as is displayed at the bottom of the About dialog
get uniqueid Requires: 7.0a Get the unique string which identifies this instance of Stickies data Return values
001 <unique_id> Remarks This has the same format as a sticky id
Other commandsThe above list is certainly not complete. There are very many other attributes and commands which Stickies can handle. I've only implemented the above set of commands so that you can check out the API. The following list of potential commands gives an idea of why I've not coded them all into the app yet - each routine is a simple quick thing to write, but it would take a while to get them all done, and many would never be used.So, if you've looked at the API, and think you can use it, and would like access to more Stickies internals, drop me a line, I can add the commands you're interested in and send you an updated exe. Potential commands
| ||||||||||||||||||||||||||||||||||||
| © Tom Revell 2009 | ||||||||||||||||||||||||||||||||||||
Forum