Stickies API

Overview

The Stickies API is accessed by sending text strings to the main Stickies window. The Windows message which is used is WM_COPYDATA which is available from Windows 95 onwards, and is a way of passing small amounts of data directly between two windows.

In return, Stickies will reply with an acknowledgement of the command, and information as to whether the command has worked, and also possibly some data in return depending on the command used.

To use the API, your application will find the Stickies main window, which has a title of ZhornSoftwareStickiesMain, and then use the Windows API call SendMessage to pass a COPYDATASTRUCT which contains the command to be sent. When Stickies replies, your application will receive a WM_COPYDATA message, again with a COPYDATASTRUCT filled in. Prefix strings sent to Stickies using WM_COPYDATA with "api", meaning that for example the full string passed to SendMessage might be "api do ping".

This code to send a message to Stickies in C# is:

[DllImport("user32", EntryPoint = "FindWindowExA")] private static extern int FindWindowEx(int hWnd1, int hWnd2, string lpsz1, string lpsz2); [DllImport("user32", EntryPoint = "SendMessageA")] private static extern int ZSendMessage(int Hwnd, int wMsg, int wParam, int lParam); private const short WM_COPYDATA = 0x4A; public struct COPYDATASTRUCT {   public int dwData;   public int cbData;   public int lpData; } int hWnd = FindWindowEx(0, hWnd, null, "ZhornSoftwareStickiesMain"); string str = "api ping"; IntPtr ptr = Marshal.StringToHGlobalAnsi(str); COPYDATASTRUCT cs; cs.dwData = 12345; cs.lpData = (int)ptr; cs.cbData = str.Length + 1; int ret = ZSendMessage(hWnd, WM_COPYDATA, (int)Handle, VarPtr(cs));

...and in C++ using MFC is:

CWnd* pStickiesWnd = CWnd::FindWindow(NULL, "ZhornSoftwareStickiesMain"); CString str = "api ping"; LRESULT copyDataResult; COPYDATASTRUCT cpd; cpd.dwData = 12345; cpd.cbData = str.GetLength(); cpd.lpData = (void*)str.GetBuffer(cpd.cbData); copyDataResult = ::SendMessage(pStickiesWnd, WM_COPYDATA, (WPARAM)AfxGetApp()->m_pMainWnd->GetSafeHwnd(), (LPARAM)&cpd); str.ReleaseBuffer();

Neither of these fragments handle the receipt of messages in return - for that code, download one of the sample projects for a working application which can communicate with Stickies.

The COPYDATASTRUCT struct has a member dwData. This is an application-specific integer, which can be used as the application wants. The Stickies API uses it to identify replies to a command. When your calling application sends a command to Stickies, the COPYDATASTRUCT sent in reply will have its dwData member filled in with the same value, so that your application can be sure that the message received is a reply to the command just sent, and not an event arriving in the middle of a command.

When an event is received by your application, the dwData member is null.

Sample Code

The screenshot shows the sample application which demonstrates communication with the Stickies API, and also a single basic function. In order to send an API message to Stickies, type it in the top box, and press return. The outgoing message is then displayed in the left hand list box, and the reply in the middle one.

Part of the API includes receiving messages from Stickies when certain events occur. These are displayed in the right list box, but note that before you receive any, the applications needs to register with Stickies for events.

The code behind the !! button is a simple example of the sort of thing the API could be used for. It's a function which is never going to be built into Stickies, but nonetheless, there are probably some users of the app who would think what it does is really cool. I'll leave it as exercise for you as to whether you click the button, or read the code to work out what it does 😊.

Sample application using C#

Sample application using Visual C++

Also available is a VC++ non-MFC project command line application which sends one-way messages to Stickies. It's one-way, as command line apps have no window to which Stickies can send replies. To that end, it's rather limited in what it can do.

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 not complete - it doesn't cover every possible command. Adding a new command to the API is something I can do for you if you need it, and get an updated executable to you for development.

do ping

Check a connection to Stickies

Return values

000 OK pong 997 OK pong, with events

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

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 imagesticky [<filename>]

Requires: 8.0a

Create a new image sticky, with the default style. If you specify an image filename, that file is then loaded into the new sticky.

Return values

000 OK created: <id>

Remarks

A new, image sticky is created, and a file is optionally loaded.

do new sticky_paste

Requires: 8.0a

Create a new sticky, and pastes the clipboard contents into it

Return values

000 OK created: <id> and pasted clipboard

Remarks

The result of this command will depend on the current clipboard contents. The clipboard can contain multiple formats at the same time of the same content, and so this command will behave in the same way as if the user had performed a "paste" operation in a blank note. The new note may therefore be either a text or image one.

do new sticky_paste_plain

Requires: 8.0a

Create a new sticky, and pastes the clipboard contents into it as plain text

Return values

000 OK created: <id> and pasted text

Remarks

This command will always create a text sticky, and then place any text contents of the clipboard into it.

do new sticky_paste_image

Requires: 8.0a

Create a new sticky, and pastes the clipboard contents into it

Return values

000 OK created: <id> and pasted image 000 OK created: <id> but no image in clipboard

Remarks

The result of this command will depend on the current clipboard contents. If the clipboard contains an image, the new sticky will be an image one. If the clipboard does not contain an image, the new sticky will be a text one with no content.

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 desktop <id> appendpaste

Requires: 8.0a

Pastes the contents of the clipboard to the end of the desktop text sticky

Return values

000 OK pasted at end

Remarks

This command will do nothing if an image sticky is specified. It will paste formatted text including the formatting.

do desktop <id> appendpasteplain

Requires: 8.0a

Pastes the text contents of the clipboard to the end of the desktop text sticky

Return values

000 OK pasted plain at end

Remarks

This command will do nothing if an image sticky is specified. It will paste plain text discarding any formatting on the clipboard.

do desktop <id> copycontent

Requires: 8.0a

Copies the contents of the specified sticky to the clipboard

Return values

000 OK content copied

Remarks

The clipboard will contain either a bitmap, or formatted text, depending on whether an image or text sticky is specified.

do desktop copycontentplain

Requires: 8.0a

Copies the contents of the specified text sticky to the clipboard as plain text

Return values

000 OK plain content copied 997 sticky is image

Remarks

If an image sticky is specified, the command will fail. Otherwise, the contents of the sticky are placed onto the clipboard as plain text.

do manage open

Open the Manage dialog

Return values

000 opened 997 it's already open

Remarks

Open the Manage dialog

do manage close

Close the manage dialog

Return values

000 closed 998 it's already 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 996 Menu command already exists

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 997 Not found to remove

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 996 Menu command already exists

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 997 Not found to remove

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 997 already registered

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 Stickies' list of API clients to which to send messages.

do deregister

Cease sending of events

Return values

000 no more events will be sent 997 not registered in the first place

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 997 unable to roll up

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

Requires: 7.0a

Performs a backup of all Stickies data to the specified filename

Return values

000 backup taken 997 Failure during backup

Remarks

Copies all live data into the specified file. If the file already exists, it will be overwritten without prompting

do sleep <id> <waketime> <options>

Requires: 7.0a

Send the specified sticky to sleep

Return values

000 slept 995 not found 997 invalid syntax

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 995 not found

Remarks

Moves a desktop sticky to the sleeping list, to wake repeatedly from the firstwake to the lastwake, according to the schedule:

Typetypehoursminutesdays
Daily1hourminuten/a
Weekly2hourminutemon:1 tue:2 wed:4 - sum those
Monthly (day of month)3hourminuteday
Yearly4hourminuteday + 100*month
Monthly (position)5hourminuteday of week + 100*code
Every6n/aquantity0=mins, 1=hours, 2=days, 3=weeks

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 995 not found 997 unable to wake

Remarks

Move a sleeping or recurring sticky to the desktop. Recurring stickies will no longer recurr once woken with this command

do new encoded <encoded string>

Requires: 8.0a

Creates a new sticky from the encoded string. If the encoding includes the <SLEEPING> tag, the new sticky will be a sleeping/recurring one. This command supercedes do new sleeping encoded, which is still a valid command.

Return values

000 OK created: <id>

Remarks

Create a new desktop, sleeping, attached or recurring sticky from the encoded string. This must be correctly formatted, see the return from the get desktop <id> encoded command for an example of this format.

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 995 not found

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 995 not found

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 995 not found

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

do saveini

Requires: 7.1a

Save the main Stickies data file immediately, ensuring any last-minute changes have been written to disk.

Return values

000 saved 995 problem saving

Remarks

Does the same as pressing control-shift-s in a sticky, but doesn't display the balloon tray hint. The data is now stored in a .db file instead of a .ini file but the command remains the same for the sake of backwards compatibility.

do netsend <id> address <address>

Requires: 7.1a

Send the desktop sticky identified over the network to another instance of Stickies.

Return values

000 sent 994 unable to send 995 not found 997 unrecognised netsend method

Remarks

The <address> can be either an IP address, or a hostname. If you need to send the sticky to a different port, then add a colon, and then the port number, eg 172.168.16.128:8874

do recreateicon

Requires: 8.0a

Force the notification tray icon to be recreated

Return values

000 OK recreated

Remarks

Under Windows 98, there was a relatively common problem when Explorer crashed that tray icons would not be recreated. Stickies has handled this problem for many versions (reacting to the WM_TASKBARCREATED message). However, if for any reason the tray icon no longer exists, calling this command will cause it to be created again.

do reindex

Requires: 10.1a

Re-crawls text for search results

Return values

000 reindexed

Remarks

Running this should never be needed - but in case the text search function does become faulty, this API command will allow the user to fix it.

set skin <pathname>

Set the main Stickies skin to be the file specified

Return values

000 set 997 unable to load file 997 forbidden by GPO

Remarks

The Stickies skin is set to the pathname in the command, and all notes 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 current main Stickies skin file

Return values

001 <skinfile_path>

Remarks

Return the path to the currently loaded main skin file. If the default built-in skin is the current one, the path will be blank.

get version

Get the version of Stickies which is running

Return values

001

Remarks

Return the Stickies version, in the format "Stickies vX.XX"

get datafile

Requires: 10.0a

Get the filename Stickies is currently using for data storage

Return values

001 <filename>

Remarks

Returns the data file being used for all Stickies data. The file is a SQLITE database. This command replaces the (deprecated) API command get datapath, as Stickies uses a single file instead of a collection of files in a folder as of v10.

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

Remarks

Return the text of the specified desktop sticky. The returned string is plain ASCII 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 wxh

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. The return value is an integer, the letter 'x' and another integer, e.g. 231x89

get desktop <id> ontop

Requires: 6.7a

Get the always-on-top status of the specified desktop sticky

Return values

001 0 001 1

Remarks

If the note 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 extensions

get desktop <id> hidden

Requires: 6.7a

Returns whether the specified desktop sticky is hidden from view

Return values

001 0 001 1

Remarks

The return value 0 means the note is visible on screen. The return value 1 means the note is currently hidden from view.

get desktop <id> ghost

Requires: 6.7a

Returns whether the specified desktop note has 'ghost' mode enabled

Return values

001 0 001 1

Remarks

The return value 0 means the note is 'normal'. The return value 1 means the note 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

Remarks

The value is a percentage, between 0 and 100. Either 0 or 100 means the note is opaque. Lower percentages mean the note 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> 997 no data

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 note are altered:

The modified value is not altered when these attributes are changed:

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 was saved to the ini file prior to v10. The format is relatively self-explanatory - make contact if you need more information.

get desktop <id> type

Requires: 7.0a

Returns an integer describing the type of note: rtf or text

Return values

001 0 001 1 998 sticky not found

Remarks

0 is a RTF (text) note, 1 is an image note

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 001 1 998 sticky not found

Remarks

0 is not rolled up. 1 is rolled up.

get desktop <id> skinpath

Requires: 7.0a

Returns the skin file the note is using

Return values

001 <path_to_file> 001 998 sticky not found

Remarks

If the specified note is using a custom skin, the path to the file is returned. Otherwise, if the note 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

000 OK created: <id>

Remarks

The return value is an ASCII string, as ASCII is what the API use. In order to transmit 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
This breaks down to the following: 0053 0074 0069 0063 006B 0069 0065 0073
The first character is therefore 0x53, which is 83, which is Unicode (and ASCII) "S"

get desktop <id> utext

Requires: 8.0b

Return the unicode-formatted text of the specified sticky

Return values

001 <encoded_unicode>

Remarks

See the detials for the command get desktop <id> utitle for details on how the return value is encoded.

get desktop <id> rtf

Requires: 7.1c

Return the RTF content of the specified sticky

Return values

001 <rtf>

Remarks

If passed the ID of an image note, "empty" RTF will be returned, so check the type with get desktop <id> type first.

get desktop <id> altwidth

Requires: 9.0a

Return the alternate width of the specified desktop sticky

Return values

001 <rtf>

Remarks

This command gets the alternate width of the specified note when it's rolled up, and the Stickies setting "Rolled notes have a different position ..." is checked.

get desktop <id> altposition

Requires: 9.0a

Return the alternate position of the specified desktop sticky

Return values

001 <x>,<y>

Remarks

This command gets the alternate position of the specified note when it's rolled up, and the Stickies option "Rolled notes have a different position ..." is checked.

get stack <id> utitle

Requires: 8.0a

Return the encoded unicode title of the specified stack

Return values

001 <utitle>

Remarks

See the remarks for the get desktop utitle command for more details on how this should be formatted.

get attached <id> encoded

Requires: 8.0a

Returns an encoded string containing all elements of the attached sticky

Return values

001 <encoded string>

Remarks

The format of the string is the same as was saved to the ini file prior to v10 of Stickies.

get sleeping <id> encoded

Requires: 7.0a

Returns an encoded string containing all elements of the sleeping or recurring sticky

Return values

001 <encoded string>

Remarks

The format of the string is the same as was saved to the ini file prior to v10 of Stickies.

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.

get closed <id> encoded

Requires: 7.1c

Returns an encoded string containing all elements of the Closed sticky

Return values

001 <CLOSED>01234567<encoded string>

Remarks

The start of the return value is the date and time on which the note was closed. This is preceded by the literal text <CLOSED>, and then followed by an encoded string.

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 note

Return values

000 source set

Remarks

Set the source of the specified desktop note

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

set desktop <id> hidden <0|1>

Requires: 6.7a

Hides or reveals the specified desktop sticky

Return values

000 hidden set

Remarks

Hidden desktop notes are just that - they do not appear on the screen although they do appear in a list of desktop notes. 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

Notes with 'ghost' mode cannot be clicked on. They appear on the desktop along with all other note, and if focus is transferred to one (by control-tabbing to it, or double-clicking it in the Desktop category 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 note in z-order.

set desktop <id> transparency <0-100>

Requires: 6.7a

Sets the transparency level of the specified desktop note

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 997 style not set 996 sticky is read only

Remarks

Sets the specified desktop note 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 note

Return values

000 title set 998 sticky not found

Remarks

The <utitle> parameter must be a string formatted in groups of four hex characters - see the remarks for the get desktop <id> utitle command for more details on how this should be formatted.

set desktop <id> utext <encoded_text>

Requires: 8.0b

Sets the Unicode-formatted text content of the specified note

Return values

000 text set 998 sticky not found

Remarks

The <encoded_text> parameter must be a string formatted in groups of four hex characters - see the remarks for the get desktop <id> utitle command for more details on how this should be formatted.

set desktop <id> image <path>

Requires: 7.0a

Converts the specified note to an image note, and loads the file specified

Return values

000 image set 998 sticky not found

Remarks

If the note 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 note

Return values

000 rtf set 997 sticky is image 998 sticky not found

Remarks

If the note is an image note, 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 998 sticky not found

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 note

Return values

000 modified set 998 sticky not found

Remarks

Sets the last modified time of a Desktop note 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 997 forbidden by GPO 997 unable to set skin 998 sticky not found

Remarks

Alters the skin which the specified note uses. The <path> parameter can be either the path to a .ssk or .ini file, or the value <default> which will set the note skin back to the user's current default.

set desktop <id> size <x>x<y>

Requires: 9.0a

Sets the size of the desktop sticky.

Return values

000 position set 996 sticky is image

Remarks

Image notes can't have their size set manually, so an error will be returned if this command specifies an image note. A side effect of running this command is that scrollbars will be enabled for the note specified.

set desktop <id> altwidth <x>

Requires: 9.0a

Sets the alternate size of the desktop note

Return values

000 alt width set

Remarks

This value changes the width of the specified note when it's rolled up, and the Stickies setting "Rolled notes have a different position ..." is checked.

set desktop <id> altposition <x>

Requires: 9.0a

Sets the alternate position of the desktop sticky

Return values

000 alt position set

Remarks

This value changes the position of the specified note when it's rolled up, and the Stickies setting "Rolled notes have a different position ..." is checked.

set sleeping <id> waketime <time>

Requires: 7.0a

Alter the wake time of a sleeping note

Return values

000 wake time set

Remarks

The

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

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 note is separated by a comma. The list is terminated with a comma. Desktop notes are those which appear in the Desktop category in the Manage dialog.

get list stacks

Requires: 8.0a

Get a list of the current stacks

Return values

001 id,id,id...

Remarks

The id of each stack, seperated by a comma. The list is terminated with a comma.

get list attached

Requires: 8.0a

Get a list of unique ids of the notes attached to any window, which are currently not visible

Return values

001 id,id,id...

Remarks

The id of each attached note is separated by a comma. The list is terminated with a comma.

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 note is separated by a comma. The list is terminated with a comma.

get list closed

Get a list of unique ids of the notes currently in the Closed category

Return values

001 id,id,id...

Remarks

The id of each Closed sticky is separated by a comma. The list is terminated with a comma.

get list stored <key>

Requires: 8.0a

Get a list of database record keys of the stickies currently in the category which has the specified key

Return values

001 key,key,key...

Remarks

The key of each Stored note is separated by a comma. The list is terminated with a comma. The input key is the value of the 'key' column of the 'categories' table in the SQLITE database file. The output is the list of 'key' values from the 'stickies' table which are in that category.

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 uniqueid

Requires: 7.0a

Get the unique string which identifies this instance of Stickies data

Return values

001 <unique_id>

Remarks

This is a Windows GUID

get snap

Requires: 7.1b

Get snapping settings

Return values

001 enabled,tolerance,distance

Remarks

Retrieve options around snapping, getting whether the feature is enabled, and the tolerance (pixels below which the note will snap) and distance (pixel distance to move to)

get stack <id> position

Requires: 9.0a

Gets the position of the stack. Stack IDs are different from sticky IDs, and are integers.

Return values

001 x,y

Remarks

Gets the position on the screen of the stack, specified by the stack ID. Get a list of stacks using get list stacks

get stack <id> size

Requires: 9.0a

Gets the size of the stack. Stack IDs are different from note IDs, and are integers.

Return values

001 <x>x<y>

Remarks

The return value is two integers which are the width and height, seperated by the 'x' character. So, you may get perhaps 200x100 as a return value, or 700x5.

set stack <id> position <x>,<y>

Requires: 9.0a

Sets the position of the specified stack. Stack IDs are different from note IDs, and are integers.

Return values

000 position set

Remarks

Place the specified stack on the screen at the x and y coordinates

get option RolledHasAltPosition

Requires: 9.0a

Gets the value of the Stickies option for whether rolled notes have an alternate location on screen.

Return values

000 1 000 0

Remarks

1 means that the option is checked. 0 means that the option is not checked.

set option <name>=<value>

Requires: 9.0a

Sets a Stickies option.

Return values

000 option set

Remarks

Using this command, all settings stored in the [options] table can be altered. The same code processes this command as handles the loading of that file, so in order to work out what the name of each option is, look at the [options] table. Although all options can be altered this way, not all will come into effect before Stickies is restarted. These include shadow, taskbar, high contrast, manage list dates, networking, RTL and hotkeys. The Settings dialog will update in real-time, however.

Events

The following is description of each of the events which your application may be sent, once it's registered with Stickies for events. Some you may want to ignore, others you may need to process.

Text in <angle brackets> is a parameter - it will change according to the current state of Stickies.

500 created desktop sticky <reason> <uniqueid>

A desktop sticky with the specified unique id has been created, for the specified reason

Remarks

The unique id identifies a sticky which has just been created on the desktop. It will now be visible to the user, and can be queried for additional values by the API. The basic source of this message is that a user has created a new note. However, it will also be generated whenever any activity causes a new sticky to appear - loading Stickies, copying an existing one, an attached sticky appearing and so on.

The reason given explains why the sticky has been created. It will be one of the following values:

501 closed desktop sticky <reason> <uniqueid>

The specified desktop note has been closed

Remarks

The note has been closed, and is now in the Closed stickies list. It is no longer be accessible on the desktop to the user, or to the API.

The reason given explains why the note has been closed. It will be one of the following values:

502 deleted desktop sticky <uniqueid>

The specified sticky has been deleted from the desktop

Remarks

This command indicates that the note has been permanently removed from the desktop. One cause of this is that the user has shift-deleted it, or perhaps that they store no closed stickies, but it may also mean that the note has been sent to sleep, moved to file, or stored. The event means that it is gone, and has not been added to the Closed list of notes. The note is no longer available on the desktop to the user, or to the API.

503 stickies is exiting

Stickies is terminating

Remarks

Stickies is terminating. No more communication will be possible until it is restarted. If your application was registered, it will need to re-register for events when Stickies is running again.

504 custom Stickies command: <command>

A custom menu command was clicked on the Stickies task-tray menu

Remarks

The custom command string which this event contains details which of the custom commands, added with the do stickymenuadd command above the user has clicked. Your application should check that the command is one which it needs to respond to, as any command clicked in Stickies will cause this event to be sent to all registered API clients.

505 custom sticky command: <command> <id>

A custom menu command was clicked on a sticky right-click menu

Remarks

The custom command string which this event contains details which of the custom commands, added with the do stickiesmenuadd command above the user has clicked. Your application should check that the command is one which it needs to respond to, as any command clicked in Stickies will cause this event to be sent to all registered API clients. The unique id identifies which sticky the user has selected, and clicked this menu item on.

506 desktop sticky focus <id>

The user clicked the mouse into a desktop note

Remarks

Used to identify the currently selected note - this event is sent when any desktop note gains input focus.

507 desktop sticky lostfocus <id>

The user moved input focus away from a desktop note

Remarks

This event is sent when any desktop note loses input focus, when the user clicks either onto another application, the desktop or perhaps another note.

508 deleted closed sticky <id>

A note was permanently removed from the application

Remarks

When a note is closed, it usually passes into the Closed notes list - unless the user either bypasses the Closed category by shift-deleting it, or perhaps if they choose to keep zero Closed notes. This event also fires when the oldest Closed note is permenently removed, because the user has closed a desktop note, and more room needs to be made in the Closed category.

509 desktop sticky moved <id>[,<id>]

Requires: 8.0c

The desktop note, or notes, were moved

Remarks

One or more desktop stickies were moved on the screen. Use the API command get desktop <id> position to retrieve the new position of any note. The unique ID is a list of IDs terminated with a comma - this may be just one note, or more than one note if the user has moved a number of notes at once.

510 desktop sticky sized <id>

Requires: 8.0c

A desktop sticky was resized

Remarks

The desktop note identified by the ID has had its size altered. In order to determine the new size, use the command get desktop <id> size.

511 created stack <id>

Requires: 9.0a

A new stack was created

Remarks

Stack IDs are in a different range than note IDs, and are an integer.

512 closed stack <id>

Requires: 9.0a

A stack was closed

Remarks

Stack IDs are in a different range than ntoe IDs, and are an integer.

513 stack moved <id> to <x>,<y>

Requires: 9.0a

The specified stack was moved on screen to the location specified.

Remarks

The stack has been moved by the user dragging it.

514 stack sized <id> to <w>x<h>

Requires: 9.0a

A stack was sized

Remarks

The specified stack has been sized by the user

515 backup taken to: <path>

Requires: 9.0a

A backup has been taken

Remarks

This may have been a scheduled backup, generated by Stickies, or instead a manual backup created by the user.

516 stickies is exiting for a restore from: <path>

Requires: 9.0a

All Stickies data is about to be restored

Remarks

Immediately following this API command, Stickies will become unresponsive to further commands for a period, while it copies the data into place and then restarts to pick up that data. Following this operation, anything your application knows about notes, stacks, options ... or anything else may be completely different.

517 desktop sticky rolled <id>
517 desktop sticky unrolled <id>

Requires: 9.0a

The status of the specified desktop note has changed

Remarks

A slightly different message is received depending on whether the note was rolled up, or was unrolled.