Difference between revisions of "Code::Blocks SDK events"

From Code::Blocks
m (ccb* => cb*)
 
(29 intermediate revisions by 2 users not shown)
Line 6: Line 6:
  
 
''Note: since mid-November 2007, loggers registration is handled with events too.''
 
''Note: since mid-November 2007, loggers registration is handled with events too.''
 +
 +
''Note: The SDK version number is defined in 'cbplugin.h'''
  
  
 
=== Available events ===
 
=== Available events ===
There are many event constants defined for the interesting events that happens inside Code::Blocks. These constants are defined in <tt>include/sdk_events.h</tt> and listed at the bottom of this page.
+
There are many event constants defined for the interesting events that happens inside Code::Blocks. These constants are defined in  
 +
<tt>include/sdk_events.h</tt>  
 +
and listed at the bottom of this page.
  
 
Also note that there 4 different event categories:
 
Also note that there 4 different event categories:
Line 37: Line 41:
  
 
And that's it. After using the above code, the defined function will be called-back on each editor saving :).
 
And that's it. After using the above code, the defined function will be called-back on each editor saving :).
 
 
 
'''Important note:''' For various reasons, cbEVT_PIPEDPROCESS* and cbEVT_THREADEDTASK* events should still be bound using the old way (i.e. by adding event table entries). If this is changed in the future, this article will be updated accordingly.
 
  
 
=== Unsubscribing from events ===
 
=== Unsubscribing from events ===
 
Usually there is no need to unsubscribe from event notifications. A plugin, for example, is automatically removed from all event notifications when it is detached (deactivated, unloaded, uninstalled).
 
Usually there is no need to unsubscribe from event notifications. A plugin, for example, is automatically removed from all event notifications when it is detached (deactivated, unloaded, uninstalled).
  
But if you really think you need to unsubscribe from events, there is a function to do that: <tt>Manager::Get()->RemoveAllEventSinksFor(void* owner)</tt>. As the sole argument, pass the instance that you registered the events in the first place.
+
But if you really think you need to unsubscribe from events, there is a function to do that:  
 +
<tt>Manager::Get()->RemoveAllEventSinksFor(void* owner)</tt>  
 +
As the sole argument, pass the instance that you registered the events in the first place.
  
 
Notice that this function will remove ''all event notifications'' for the specified instance. There is no way to remove event notifications selectively. It's an all-or-nothing deal...
 
Notice that this function will remove ''all event notifications'' for the specified instance. There is no way to remove event notifications selectively. It's an all-or-nothing deal...
 
  
 
=== When to register/unregister for event notifications? ===
 
=== When to register/unregister for event notifications? ===
In plugins, event notifications should be registered in <tt>OnAttach()</tt>. As mentioned above, there is no need to unregister anything in <tt>OnDetach()</tt> because it is automatically done by Code::Blocks.
+
In plugins, event notifications should be registered in  
 +
<tt>OnAttach()</tt>  
 +
As mentioned above, there is no need to unregister anything in
 +
<tt>OnDetach()</tt>  
 +
because it is automatically done by Code::Blocks.
  
 
For code other than plugins, register whenever you think is better (depends on the actual code).
 
For code other than plugins, register whenever you think is better (depends on the actual code).
  
 
Also notice that Code::Blocks removes all registrations on shut down, so don't even think that we have memory leaks in that part ;).
 
Also notice that Code::Blocks removes all registrations on shut down, so don't even think that we have memory leaks in that part ;).
 
  
 
=== Any examples? ===
 
=== Any examples? ===
If the example provided above is not enough, browse through the sources of the core/contrib Code::Blocks plugins. A few of them register for events: just search the code for <tt>RegisterEventSink</tt>.
+
If the example provided above is not enough, browse through the sources of the core/contrib Code::Blocks plugins.  
 +
A few of them register for events: just search the code for  
 +
<tt>RegisterEventSink</tt>
 
But it really is nothing difficult: just remove the event handlers from the class's event table and register with this new way.
 
But it really is nothing difficult: just remove the event handlers from the class's event table and register with this new way.
  
Line 65: Line 71:
  
 
=== List of Available Code::Blocks Events ===
 
=== List of Available Code::Blocks Events ===
 +
 +
==== List of SDK versions ====
 +
[https://forums.codeblocks.org/index.php/topic,19981.msg136485.html#msg136485 SDK versions] with dates
  
 
==== Events that must be registered with RegisterEventSink (from 'sdk_events.cpp') ====  
 
==== Events that must be registered with RegisterEventSink (from 'sdk_events.cpp') ====  
 +
==> updated (May 03, 2021)
 +
 
''app events''
 
''app events''
 
* cbEVT_APP_STARTUP_DONE
 
* cbEVT_APP_STARTUP_DONE
 
* cbEVT_APP_START_SHUTDOWN
 
* cbEVT_APP_START_SHUTDOWN
* cbEVT_APP_START_ACTIVATED (sdk 1.19.0)
+
* cbEVT_APP_ACTIVATED (sdk 1.19.0)
* cbEVT_APP_START_DEACTIVATED (sdk 1.19.0)
+
* cbEVT_APP_DEACTIVATED (sdk 1.19.0)
* <strike>cbEVT_APP_UPDATE_TITLE</strike> (removed)
+
* cbEVT_APP_CMDLINE
  
 
''plugin events'' (CodeBlocksEvent)
 
''plugin events'' (CodeBlocksEvent)
 
* cbEVT_PLUGIN_ATTACHED
 
* cbEVT_PLUGIN_ATTACHED
 
* cbEVT_PLUGIN_RELEASED
 
* cbEVT_PLUGIN_RELEASED
* cbEVT_PLUGIN_INSTALLED
+
* cbEVT_PLUGIN_INSTALLED : plugin manually loaded
* cbEVT_PLUGIN_UNINSTALLED
+
* cbEVT_PLUGIN_UNINSTALLED : plugin manually unloaded
 
* cbEVT_PLUGIN_LOADING_COMPLETE (sdk 1.19.0)
 
* cbEVT_PLUGIN_LOADING_COMPLETE (sdk 1.19.0)
  
Line 92: Line 103:
 
* cbEVT_EDITOR_TOOLTIP
 
* cbEVT_EDITOR_TOOLTIP
 
* cbEVT_EDITOR_TOOLTIP_CANCEL
 
* cbEVT_EDITOR_TOOLTIP_CANCEL
* <strike>cbEVT_EDITOR_BREAKPOINT_ADD</strike> (removed 1.19.0)
+
* cbEVT_EDITOR_SPLIT
* <strike>cbEVT_EDITOR_BREAKPOINT_EDIT</strike> (removed 1.19.0)
+
* cbEVT_EDITOR_UNSPLIT
* <strike>cbEVT_EDITOR_BREAKPOINT_DELETE</strike> (removed 1.19.0)
 
 
* cbEVT_EDITOR_UPDATE_UI
 
* cbEVT_EDITOR_UPDATE_UI
 +
* cbEVT_EDITOR_CC_DONE
  
 
''project events'' (CodeBlocksEvent)
 
''project events'' (CodeBlocksEvent)
Line 108: Line 119:
 
* cbEVT_PROJECT_END_REMOVE_FILES
 
* cbEVT_PROJECT_END_REMOVE_FILES
 
* cbEVT_PROJECT_FILE_ADDED
 
* cbEVT_PROJECT_FILE_ADDED
 +
* cbEVT_PROJECT_FILE_CHANGED
 
* cbEVT_PROJECT_FILE_REMOVED
 
* cbEVT_PROJECT_FILE_REMOVED
* cbEVT_PROJECT_FILE_CHANGED
+
* cbEVT_PROJECT_FILE_RENAMED (sdk 2.7.0)
 
* cbEVT_PROJECT_POPUP_MENU
 
* cbEVT_PROJECT_POPUP_MENU
 
* cbEVT_PROJECT_TARGETS_MODIFIED
 
* cbEVT_PROJECT_TARGETS_MODIFIED
Line 115: Line 127:
 
* cbEVT_PROJECT_OPTIONS_CHANGED (sdk 1.19.0)
 
* cbEVT_PROJECT_OPTIONS_CHANGED (sdk 1.19.0)
 
* cbEVT_WORKSPACE_CHANGED
 
* cbEVT_WORKSPACE_CHANGED
* cbEVT_CLEAN_WORKSPACE_LOADING_COMPLETE (sdk 1.19.0)
+
* cbEVT_WORKSPACE_LOADING_COMPLETE (sdk 1.19.0)
 +
* cbEVT_WORKSPACE_CLOSING_BEGIN  (sdk 1.19.0)
 +
* cbEVT_WORKSPACE_CLOSING_COMPLETE (sdk 1.19.0)
  
 
''build targets events'' (CodeBlocksEvent) (sdk 1.19.0)
 
''build targets events'' (CodeBlocksEvent) (sdk 1.19.0)
 
* cbEVT_BUILDTARGET_ADDED
 
* cbEVT_BUILDTARGET_ADDED
 
* cbEVT_BUILDTARGET_REMOVED
 
* cbEVT_BUILDTARGET_REMOVED
* cbEVT_BUILDTARGET_RENOMED
+
* cbEVT_BUILDTARGET_RENAMED
 
* cbEVT_BUILDTARGET_SELECTED
 
* cbEVT_BUILDTARGET_SELECTED
  
Line 138: Line 152:
 
* cbEVT_SHOW_DOCK_WINDOW: request app to show a docked window
 
* cbEVT_SHOW_DOCK_WINDOW: request app to show a docked window
 
* cbEVT_HIDE_DOCK_WINDOW: request app to hide a docked window
 
* cbEVT_HIDE_DOCK_WINDOW: request app to hide a docked window
* cbEVT_DOCK_WINDOW_VISIBILITY: app notifies that a docked window has been hidden/shown to actually find out its state use IsWindowReallyShown(event.pWindow);
 
  
 
''layout related events'' (CodeBlocksDockEvent)  
 
''layout related events'' (CodeBlocksDockEvent)  
Line 144: Line 157:
 
* cbEVT_QUERY_VIEW_LAYOUT : ask which is the current view layout
 
* cbEVT_QUERY_VIEW_LAYOUT : ask which is the current view layout
 
* cbEVT_SWITCH_VIEW_LAYOUT : request app to switch view layout
 
* cbEVT_SWITCH_VIEW_LAYOUT : request app to switch view layout
* <strike>cbEVT_SWITCHED_VIEW_LAYOUT</strike> (removed 1.19.0) : app notifies that a new layout has been applied
+
* cbEVT_SWITCHED_VIEW_LAYOUT : app notifies that a new layout has been applied
 +
* cbEVT_DOCK_WINDOW_VISIBILITY : app notifies that a docked window has been hidden/show
  
 
''main menubar creation'' (CodeBlocksEvent)
 
''main menubar creation'' (CodeBlocksEvent)
Line 163: Line 177:
 
* cbEVT_DEBUGGER_PAUSED
 
* cbEVT_DEBUGGER_PAUSED
 
* cbEVT_DEBUGGER_FINISHED
 
* cbEVT_DEBUGGER_FINISHED
 +
* cbEVT_DEBUGGER_UPDATED (sdk 1.38.0)
 +
* cbEVT_DEBUGGER_CURSOR_CHANGED
 +
* cbEVT_DEBUGGER_CONTINUED (sdk 1.38.0)
  
 
''logging-system related events'' (CodeBlocksLogEvent)
 
''logging-system related events'' (CodeBlocksLogEvent)
Line 169: Line 186:
 
* cbEVT_HIDE_LOG_WINDOW (sdk 1.19.0) : hide a log window
 
* cbEVT_HIDE_LOG_WINDOW (sdk 1.19.0) : hide a log window
 
* cbEVT_SWITCH_TO_LOG_WINDOW : switch to a log window (make it visible)
 
* cbEVT_SWITCH_TO_LOG_WINDOW : switch to a log window (make it visible)
* cbEVT_GET_LOG_WINDOW (sdk 1.19.0)
+
* cbEVT_GET_ACTIVE_LOG_WINDOW 
 
* cbEVT_SHOW_LOG_MANAGER: show log manager
 
* cbEVT_SHOW_LOG_MANAGER: show log manager
 
* cbEVT_HIDE_LOG_MANAGER: hide log manager
 
* cbEVT_HIDE_LOG_MANAGER: hide log manager
Line 183: Line 200:
  
 
* cbEVT_SETTINGS_CHANGED
 
* cbEVT_SETTINGS_CHANGED
 
==== Events processed on wxWidgets event tables and '''not''' registered using RegisterEventSink ====
 
''pipedprocess events'' (CodeBlocksEvent)
 
* cbEVT_PIPEDPROCESS_STDOUT
 
* cbEVT_PIPEDPROCESS_STDERR
 
* cbEVT_PIPEDPROCESS_TERMINATED
 
 
''thread-pool events'' (CodeBlocksEvent)
 
* cbEVT_THREADTASK_STARTED
 
* cbEVT_THREADTASK_ENDED
 
* cbEVT_THREADTASK_ALLDONE
 
  
  
 
[[User:Mandrav|Mandrav]] 10:31, 23 November 2007 (UTC)
 
[[User:Mandrav|Mandrav]] 10:31, 23 November 2007 (UTC)

Latest revision as of 12:53, 25 May 2022

During a Code::Blocks session, many things are happening: projects/files loading, closing, activating, saving, etc. These are interesting things that happen and various parts of Code::Blocks and its plugins are interested in them. The Code::Blocks SDK provides functions that allow a part of the code to be "subscribed" to these events (i.e. be notified when they happen). This is what we'll look at in this article.

Note: since mid-November 2007, loggers registration is handled with events too.

Note: The SDK version number is defined in 'cbplugin.h'


Available events

There are many event constants defined for the interesting events that happens inside Code::Blocks. These constants are defined in

include/sdk_events.h 

and listed at the bottom of this page.

Also note that there 4 different event categories:

  • Logging system related (CodeBlocksLogEvent)
  • View layout related (CodeBlocksLayoutEvent)
  • Docking system related (CodeBlocksDockEvent)
  • and everything else (CodeBlocksEvent)

Subscribing to events

Up until July 6th (2007) rev4233, Code::Blocks events were handled like other wxWidgets events: by declaring an event table in your class that should handle them and adding relevant event table entries.

But the event system changed radically on July 6th (2007) rev4234, in order to battle some shortcomings of the wxWidgets event system (at least for our usage). While designing the new system, great attention has been paid so that plugin writers have to do minimum changes to convert their code.

The class that handles all event registrations is the central class in Code::Blocks which you use if you want to do anything with the Code::Blocks SDK: Manager. Let's see by example how would a class (e.g. SomePlugin) subscribe for the cbEVT_EDITOR_SAVE event (fired when an editor's contents are saved):

// assuming an existing member function:
// void SomePlugin::OnEditorSaved(CodeBlocksEvent& event);

Manager::Get()->RegisterEventSink(cbEVT_EDITOR_SAVE, new cbEventFunctor<SomePlugin, CodeBlocksEvent>(this, &SomePlugin::OnEditorSaved));

Seems difficult? It isn't, if you realize what the second argument to Manager::RegisterEventSink does.

cbEventFunctor is a class that encapsulates a this-pointer call. It is like a C function pointer except that it works with class instances (i.e. a member-function pointer). For obvious reasons it is a template class, taking two template arguments: the first is the class' name and the second is the type of the event the member function handles.

The constructor of cbEventFunctor takes two arguments: first is the class instance (we use the this pointer) and the second is the address of the member function.

And that's it. After using the above code, the defined function will be called-back on each editor saving :).

Unsubscribing from events

Usually there is no need to unsubscribe from event notifications. A plugin, for example, is automatically removed from all event notifications when it is detached (deactivated, unloaded, uninstalled).

But if you really think you need to unsubscribe from events, there is a function to do that:

Manager::Get()->RemoveAllEventSinksFor(void* owner) 

As the sole argument, pass the instance that you registered the events in the first place.

Notice that this function will remove all event notifications for the specified instance. There is no way to remove event notifications selectively. It's an all-or-nothing deal...

When to register/unregister for event notifications?

In plugins, event notifications should be registered in

OnAttach() 

As mentioned above, there is no need to unregister anything in

OnDetach() 

because it is automatically done by Code::Blocks.

For code other than plugins, register whenever you think is better (depends on the actual code).

Also notice that Code::Blocks removes all registrations on shut down, so don't even think that we have memory leaks in that part ;).

Any examples?

If the example provided above is not enough, browse through the sources of the core/contrib Code::Blocks plugins. A few of them register for events: just search the code for

RegisterEventSink

But it really is nothing difficult: just remove the event handlers from the class's event table and register with this new way.

Try using the DisplayEvents plugin if there is any difficulty determining which events to register.

List of Available Code::Blocks Events

List of SDK versions

SDK versions with dates

Events that must be registered with RegisterEventSink (from 'sdk_events.cpp')

==> updated (May 03, 2021)

app events

  • cbEVT_APP_STARTUP_DONE
  • cbEVT_APP_START_SHUTDOWN
  • cbEVT_APP_ACTIVATED (sdk 1.19.0)
  • cbEVT_APP_DEACTIVATED (sdk 1.19.0)
  • cbEVT_APP_CMDLINE

plugin events (CodeBlocksEvent)

  • cbEVT_PLUGIN_ATTACHED
  • cbEVT_PLUGIN_RELEASED
  • cbEVT_PLUGIN_INSTALLED : plugin manually loaded
  • cbEVT_PLUGIN_UNINSTALLED : plugin manually unloaded
  • cbEVT_PLUGIN_LOADING_COMPLETE (sdk 1.19.0)

editor events (CodeBlocksEvent)

  • cbEVT_EDITOR_CLOSE
  • cbEVT_EDITOR_OPEN
  • cbEVT_EDITOR_SWITCHED
  • cbEVT_EDITOR_ACTIVATED
  • cbEVT_EDITOR_DEACTIVATED
  • cbEVT_EDITOR_BEFORE_SAVE (sdk 1.19.0)
  • cbEVT_EDITOR_SAVE
  • cbEVT_EDITOR_MODIFIED
  • cbEVT_EDITOR_TOOLTIP
  • cbEVT_EDITOR_TOOLTIP_CANCEL
  • cbEVT_EDITOR_SPLIT
  • cbEVT_EDITOR_UNSPLIT
  • cbEVT_EDITOR_UPDATE_UI
  • cbEVT_EDITOR_CC_DONE

project events (CodeBlocksEvent)

  • cbEVT_PROJECT_NEW (sdk 1.19.0)
  • cbEVT_PROJECT_CLOSE
  • cbEVT_PROJECT_OPEN
  • cbEVT_PROJECT_SAVE
  • cbEVT_PROJECT_ACTIVATE
  • cbEVT_PROJECT_BEGIN_ADD_FILES
  • cbEVT_PROJECT_END_ADD_FILES
  • cbEVT_PROJECT_BEGIN_REMOVE_FILES
  • cbEVT_PROJECT_END_REMOVE_FILES
  • cbEVT_PROJECT_FILE_ADDED
  • cbEVT_PROJECT_FILE_CHANGED
  • cbEVT_PROJECT_FILE_REMOVED
  • cbEVT_PROJECT_FILE_RENAMED (sdk 2.7.0)
  • cbEVT_PROJECT_POPUP_MENU
  • cbEVT_PROJECT_TARGETS_MODIFIED
  • cbEVT_PROJECT_RENAMED
  • cbEVT_PROJECT_OPTIONS_CHANGED (sdk 1.19.0)
  • cbEVT_WORKSPACE_CHANGED
  • cbEVT_WORKSPACE_LOADING_COMPLETE (sdk 1.19.0)
  • cbEVT_WORKSPACE_CLOSING_BEGIN (sdk 1.19.0)
  • cbEVT_WORKSPACE_CLOSING_COMPLETE (sdk 1.19.0)

build targets events (CodeBlocksEvent) (sdk 1.19.0)

  • cbEVT_BUILDTARGET_ADDED
  • cbEVT_BUILDTARGET_REMOVED
  • cbEVT_BUILDTARGET_RENAMED
  • cbEVT_BUILDTARGET_SELECTED

pipedprocess events (CodeBlocksEvent) (sdk 1.19.0)

  • cbEVT_PIPEDPROCESS_STDOUT
  • cbEVT_PIPEDPROCESS_STDERR
  • cbEVT_PIPEDPROCESS_TERMINATED

thread-pool events (CodeBlocksEvent) (sdk 1.19.0)

  • cbEVT_THREADTASK_STARTED
  • cbEVT_THREADTASK_ENDED
  • cbEVT_THREADTASK_ALLDONE

dockable windows (CodeBlocksDockEvent)

  • cbEVT_ADD_DOCK_WINDOW: request app to add and manage a docked window
  • cbEVT_REMOVE_DOCK_WINDOW: request app to stop managing a docked window
  • cbEVT_SHOW_DOCK_WINDOW: request app to show a docked window
  • cbEVT_HIDE_DOCK_WINDOW: request app to hide a docked window

layout related events (CodeBlocksDockEvent)

  • cbEVT_UPDATE_VIEW_LAYOUT (sdk 1.19.0) : force update current view layout
  • cbEVT_QUERY_VIEW_LAYOUT : ask which is the current view layout
  • cbEVT_SWITCH_VIEW_LAYOUT : request app to switch view layout
  • cbEVT_SWITCHED_VIEW_LAYOUT : app notifies that a new layout has been applied
  • cbEVT_DOCK_WINDOW_VISIBILITY : app notifies that a docked window has been hidden/show

main menubar creation (CodeBlocksEvent)

  • cbEVT_MENUBAR_CREATE_BEGIN: app notifies that the menubar is started being (re)created
  • cbEVT_MENUBAR_CREATE_END: app notifies that the menubar (re)creation ended

compiler-related events (CodeBlocksEvent)

  • cbEVT_COMPILER_STARTED
  • cbEVT_COMPILER_FINISHED
  • cbEVT_COMPILER_SET_BUILD_OPTIONS (sdk 1.19.0)
  • cbEVT_COMPILER_CLEAN_PROJECT_STARTED (sdk 1.19.0)
  • cbEVT_CLEAN_WORKSPACE_STARTED (sdk 1.19.0)
  • cbEVT_COMPILER_SETTING_CHANGED (sdk 1.19.0)
  • cbEVT_COMPILE_FILE_REQUEST (sdk 1.19.0) : request app to compile a single file

debugger-related events (CodeBlocksEvent)

  • cbEVT_DEBUGGER_STARTED
  • cbEVT_DEBUGGER_PAUSED
  • cbEVT_DEBUGGER_FINISHED
  • cbEVT_DEBUGGER_UPDATED (sdk 1.38.0)
  • cbEVT_DEBUGGER_CURSOR_CHANGED
  • cbEVT_DEBUGGER_CONTINUED (sdk 1.38.0)

logging-system related events (CodeBlocksLogEvent)

  • cbEVT_ADD_LOG_WINDOW: add a log window
  • cbEVT_REMOVE_LOG_WINDOW: remove a log window
  • cbEVT_HIDE_LOG_WINDOW (sdk 1.19.0) : hide a log window
  • cbEVT_SWITCH_TO_LOG_WINDOW : switch to a log window (make it visible)
  • cbEVT_GET_ACTIVE_LOG_WINDOW
  • cbEVT_SHOW_LOG_MANAGER: show log manager
  • cbEVT_HIDE_LOG_MANAGER: hide log manager
  • cbEVT_LOCK_LOG_MANAGER: "lock" it (used with auto-hiding functionality)
  • cbEVT_UNLOCK_LOG_MANAGER: "unlock" it (used with auto-hiding functionality)

cbAUiNotebook related events (CodeBlocksLogEvent) (sdk 1.19.0)

  • cbEVT_CBAUIBOOK_LEFT_DCLICK

code-completion related events (CodeBlocksLogEvent) (sdk 1.19.0)

  • cbEVT_COMPLETE_CODE
  • cbEVT_SHOW_CALL_TIP
  • cbEVT_SETTINGS_CHANGED


Mandrav 10:31, 23 November 2007 (UTC)