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.
It will return errorlevel codes 0 for OK, 1 for "can't find the Stickies window" and 2 for "Stickies didn't acknowledge the message". However, when communicating with Stickies prior to v10.1, Stickies will always cause errorlevel 1, even when the command was processed correctly.
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
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 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 desktop <note id> store <folder id>
Requires: 10.1a
Stores the specified note in the specified Store folder. If the destination folder is set to only accept encrypted notes, the note will be encrypted as it's stored. If the password has not been entered, then the operation will fail.
Return values
000 stored 998 folder not found 997 password needed before storing to encrypted folder
do stack <id> stacked
Requires: 10.1a
Moves the unstacked notes in the specified stack back into the stack. If already stacked, the return value will be "OK", but nothing will happen.
Return values
000 OK stacked
do stack <id> unstacked
Requires: 10.1a
Moves the stacked notes in the specified stack out from the stack onto the desktop. If already unstacked, the return value will be "OK", but nothing will happen.
Return values
000 OK unstacked
do stack <id> togglestacked
Requires: 10.1a
If the specified stack has the notes inside it, they will be moved out. If the stack has its notes out on the desktop, they will be moved into the stack.
Return values
000 OK stacked 000 OK unstacked
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 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:
| Type | type | hours | minutes | days |
| Daily | 1 | hour | minute | n/a |
| Weekly | 2 | hour | minute | mon:1 tue:2 wed:4 - sum those |
| Monthly (day of month) | 3 | hour | minute | day |
| Yearly | 4 | hour | minute | day + 100*month |
| Monthly (position) | 5 | hour | minute | day of week + 100*code |
| Every | 6 | n/a | quantity | 0=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
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:
- text
- title
- source
- colour
- user1
- user2
- user3
- userstring1
- alarm
The modified value is not altered when these attributes are changed:
- size
- width
- read only
- on top
- transparency
- rolled
- attached
- ghost
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
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
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 note 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 list folders
Requires: 10.1a
Get a list of unique ids of the folders currently in the Stored category
Return values
001 id,id,id...
Remarks
The id of each Stored folders 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 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:
- welcome
- loaded
- imported
- network
- new
- waking
- attached
- undeleted
- woken
- unattached
- unstored
- copied
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:
- closed
- exiting
- unattached
- stored
- network
- movetofile
- slept
502 deleted desktop sticky <reason> <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.