C H A P T E R 24

Working with Add-ins

This chapter describes how to create custom programs that are tightly integrated
with Solid Edge.
Working with Add-ins...........................................................................177
210......................................................................................................... 177
Working with Add-insOverview..........................................................179
Chapter 24 Solid Edge Programmer's !ide.....................................17"
210......................................................................................................... 17"
Implementing an Add-in......................................................................... 180
Working with Add-ins Chapter 24......................................................17#
210......................................................................................................... 17#
Working with the ISoliddgeAddIn Inter!a"e.........................................181
Working with ISAddInvents and #ISAddInvents..........................18$
177
Chapter 24 Solid Edge Programmer's Guide
Working with Solid dge O%&e"ts' Inter!a"es' and vents.....................18(
)egistering an Add-in............................................................................ *08
178
Working with Add-ins Chapter 24
Working with Add-insOverview
The Solid Edge API provides an easy-to-use set o interaces that enable programmers
to ully integrate custom commands with Solid Edge. These custom programs are
commonly reerred to as add-ins. Speciically! Solid Edge deines an add-in as a
dynamically lin"ed library #$%%& containing a '()-based ob*ect that implements the
ISolidEdgeAddIn interace. )ore generally! an add-in is a '() ob*ect that is used to
provide commands or other value to Solid Edge.
The only restriction placed on an add-in is that the add-in must use standard +indows-
based resources. An e,ample o such a resource would be device-independent bitmaps
to be added to the Solid Edge graphical user interace. -ou can create these resources
using any o the popular visual programming tools that are available in the +indows
programming environment./isual '00 or /isual 1asic! or e,ample.
The ollowing interaces are available to the add-in programmer2
ISolidEdgeAddIn.The irst interace implemented by an add-in. Provides the
initial means o communicating with Solid Edge.
ISEAddInEvents and $ISEAddInEvents.Provides command-level
communication between the add-in and Solid Edge.
In addition! several Solid Edge interaces are available once the add-in is connected to
Solid Edge. These include ISEAddIn! ISE'ommand3$ISE'ommand!
ISE'ommandEvents3$ISE'ommandEvents! ISE)ouse3$ISE)ouse!
ISE)ouseEvents3$ISE)ouseEvents! ISE+indowEvents3$ISE+indowEvents! and
ISolidEdge1ar.
179
Chapter 24 Solid Edge Programmer's Guide
Implementing an Add-in
A Solid Edge add-in has the ollowing re4uirements2
The add-in must be a sel-registering Active5 $%%. -ou must deliver a registry
script that registers the $%% and adds Solid Edge-speciic inormation to the
system registry.
The add-in must e,pose a '()-creatable class rom the $%% in the registry.
The add-in must register the 'ATI$6SolidEdgeAddin as an Implemented
'ategory in its registry setting so that Solid Edge can identiy it as an add-in.
The add-in must implement the ISolidEdgeAddIn interace. The deinition o this
interace is delivered with the Solid Edge S$7 #addins.h&. The add-in can
implement any additional interaces! but ISolidEdgeAddIn is the interace that
Solid Edge loo"s or.
$uring the (n'onnect call #made by Solid Edge on the add-in8s ISolidEdgeAddIn
interace&! the add-in can add commands to one or more Solid Edge environments.
I a graphical user interace #buttons or toolbars! or e,ample& is associated with
the add-in! then the add-in must provide a 9:I version to be stored by Solid Edge.
I the 9:I version changes the ne,t time the add-in is loaded! then Solid Edge will
purge the old 9:I and re-create it based on the calls to Add'ommand1ar1utton
with the (n'onnectToEnvironment method. A 9:I is an optional component o
an add-in; some add-ins! or e,ample! simply monitor Solid Edge events and
perorm actions based on those activities.
-ou must ollow '() rules and call Add<e on any Solid Edge pointers that the
add-in is holding on to. -ou must also release the pointers when they are no longer
needed. In /isual 1asic! Add<e is done automatically by Set SEInterace =
>Solid Edge interace?; to release the interace! set the interace to @Aothing.@
Bor /isual '00 users! a Solid Edge Add-in +iCard e,ists. The wiCard is currently
available or download rom the Solid Edge web site. The wiCard generates ully
unctional add-ins based on )icrosot8s Active Template %ibrary #AT%& or
'().
180
Working with Add-ins Chapter 24
Working with the ISolidEdgeAddIn Interface
The ISolidEdgeAddIn interace is the irst interace that is implemented by an add-in
and provides the initial means o communication with Solid Edge. It allows or
connection to and disconnection rom an add-in. The implementation o this interace
is what identiies a '() ob*ect as being a Solid Edge add-in.
OnConnection
HRESULT OnConnection( IDispatch *pApplication, seConnectMode
ConnectMode, AddIn *pAddIn )

Solid Edge passes in a pointer to the dispatch interace o the Solid Edge application
that is attempting to connect to the add-in. The add-in uses this pointer to ma"e any
necessary calls to the application to connect to Solid Edge event sin"s! or to otherwise
communicate with Solid Edge to perorm whatever tas"s the add-in needs when irst
starting up.
Solid Edge passes in a connect mode that indicates what caused Solid Edge to connect
to the add-in. 'urrent modes are as ollows2
se'onnectAtStart:p.%oading the add-in at startup.
se'onnect1y:ser.%oading the add-in at user8s re4uest.
se'onnectE,ternally.%oading the add-in due to an e,ternal #programmatic&
re4uest.
Solid Edge also passes in a dispatch interace o a Solid Edge Add-in ob*ect that
provides another channel o communication between the add-in and Solid Edge. An
e4uivalent v-table orm o this interace can be obtained by 4uerying the input Add-in8s
dispatch interace or the ISEAddIn interace #also described in addins.h&.
In general! the add-in needs to do very little needs when (n'onnection is called. Dere
are a ew basic steps that an add-in may want to perorm during connection.
1. 'onnect to any Solid Edge application event sets the add-in plans on using by
providing the appropriate sin"s to the application ob*ect.
2. 'onnect to the Solid Edge Add-in ob*ect8s event set i the add-in plans to add any
commands to any environments.
$. Set the 9:I version property o the Solid Edge Add-in ob*ect.
181
Chapter 24 Solid Edge Programmer's Guide
OnDisconnection
HRESULT OnDisconnection( SeDisconnectMode DisconnectMode )

Solid Edge passes in a disconnect mode that indicates what caused Solid Edge to
disconnect to the add-in. 'urrent modes are as ollows2
Se$isconnectAtShut$own.:nloading at shutdown.
Se$isconnect1y:ser.:nloading the add-in due to a user re4uest.
Se$isconnectE,ternally.:nloading the add-in due to an e,ternal #programmatic&
re4uest.
To disconnect! the add-in should do the ollowing2
4. $isconnect rom any Solid Edge event sets it may have connected to.
%. $isconnect rom the Add-in event set #i connected&.
&. <elease any other ob*ects or interaces the add-in may have obtained rom the
application.
7. 'lose any storage and3or streams it may have opened in the application8s
document.
". Perorm any other cleanup such as reeing any resources it may have allocated.
OnConnectToEnvironment
HRESULT OnConnectToEnvion!ent( "STR EnvCatID, L#DIS#ATCH
pEnvion!ent, $ARIA%T&"OOL* '(istTi!e )

Solid Edge passes in the category identiier o the environment as a string. I the add-in
is registered as supporting multiple environments! the add-in can use the string to
determine which environment to which it is being as"ed to connect.
Solid Edge passes in the dispatch interace o the environment.
Solid Edge passes in the bBirstTime parameter to speciy that a Solid Edge
environment is connecting to the add-in or the irst time. +hen connecting or the irst
time! the add-in! i necessary! should add any needed user interace elements #or
e,ample! buttons&. (n e,iting! Solid Edge will save any such buttons so they can be
restored during the ne,t session.
To connect to a Solid Edge environment! the add-in will perorm the ollowing steps in
its (n'onnectToEnvironment2
1. The add-in should always call the SetAddInIno method o the add-in interace
passed to it during (n'onnection i it provides any command bars or command
bar buttons in the environment.
182
Working with Add-ins Chapter 24
2. The add-in uses the bBirstTime parameter to determine i it is the irst time the
add-in has been loaded into the environment by chec"ing to see i it is
/A<IAAT6T<:E. I it is! the add-in should add any command bar buttons it
needs to carry out its commands by calling the add-in interace8s
Add'ommand1ar1utton method. I the add-in is not disconnected! and its 9:I
version has not changed the ne,t time Solid Edge loads the add-in! then Solid Edge
will set the parameter to /A<IAAT6BA%SE because Solid Edge will save the
data provided it by the add-in the last time the parameter was /A<IAAT6T<:E.
Aote that i the add-in8s (n$isconnect unction is called with a disconnect mode
dierent rom se$isconnectAtShutdown! this parameter will be
/A<IAAT6T<:E the ne,t time Solid Edge calls (n'onnection. This happens
because when an add-in is disconnected by the user or programatically! Solid Edge
will purge all 9:I modiications made by the add-in rom all environments.
$. Add any commands not included in any o the calls to SetAddInIno by calling the
application8s Add'ommand method. 9enerally this method is used when a
command is being added to the menu but not any command bar.
'ote 'ommand bars are persisted by Solid Edge when e,iting. +hen an environment
is irst loaded! connection to the add-in is perormed beore the environment8s
command bars are loaded. This allows an add-in to call SetAddInIno to supply any
glyphs needed by any buttons that were previously saved by Solid Edge.
Add-ins cannot assume the e,istence o any particular environment! until this unction
is called with that environment8s catid. Any calls with a catid or an environment that
does not yet e,ist will be re*ected.
183
Chapter 24 Solid Edge Programmer's Guide
Working with ISEAddInEvents and DISEAddInEvents
+hen an add-in adds commands to a Solid Edge environment! a system o
notiications must e,ist between the add-in and Solid Edge to enable and disable
commands! invo"e commands! and provide help or the commands. The
ISEAddinEvents interace and its e4uivalent dispatch interace! $ISEAddinEvents!
serve this purpose.
(ne o these two interaces is implemented by the add-in ob*ect and is used by Solid
Edge to invo"e commands added to Solid Edge by the add-in and to allow the add-in to
perorm basic user interace updates. The interace contains three methods2
(n'ommand! (n'ommand:pdate:I and (n'ommandDelp.
OnCommand
HRESULT OnCo!!and( lon) nC!dID )

Solid Edge calls this method! passing in n'mdI$ whenever the user invo"es an add-in
command. The value o the add-in command identiier passed in is the same value the
add-in previously gave the AddIn ob*ect when it called its SetAddInIno method.
+hen (n'ommand is called! i the add-in wants to ta"e advantage o the Solid Edge
command control or mouse control! it can create a command ob*ect using the
application8s 'reate'ommand method. 'reate'ommand returns a $ISE'ommand
interace #rom which the ISE'ommand e4uivalent v-table interace can be obtained&.
OnCommandUpdateUI
HRESULT OnCo!!andUpdateUI( lon) nC!dID, lon)* pd*C!d(la)s,
"STR Men+te,t, lon) *nID"it!ap)

Solid Edge calls this method! passing in n'mdI$ whenever it needs to determine the
availability o a command previously added to Solid Edge by the add-in. The value o
n'mdI$ will be one o the values the add-in previously passed in the SetAddInIno
method. The add-in uses the pointer to the dw'mdBlags bit mas" to enable3disable the
command and to notiy Solid Edge to ma"e other 9:I changes. The values o the
mas"s are as ollows2
se'mdActive6Enabled.:sed to enable the command.
se'mdActive6'hec"ed.:sed to add a chec" mar" on the command8s menu item.
se'mdActive6'hangeTe,t.:sed to change the te,t that appears on the
command8s menu item.
se'mdActive6:se$ot)ar".:sed to add a dot mar" on the command8s menu
item.
se'mdActive6:se1itmap.:sed to display the command8s menu item as a
bitmap.
184
Working with Add-ins Chapter 24
)enute,t can be used to change the te,t that appears on the menu. In order to change
the te,t! allocate and return the desired te,t string. nI$1itmap can be used to have a
bitmap appear on the menu ne,t to the te,t.
'ote Ater calling (n'ommand:pdate:I! Solid Edge will determine whether
se'mdActive6:se1itmap is set and i so! the returned value o nI$1itmap should
represent the resource identiier o a bitmap stored in the resource $%% whose handle
was passed in the SetAddInIno method.
This method is called to determine i a command is enabled or disabled. It is called or
commands visible on toolbars during idle processing! *ust beore displaying a menu!
when an accelerator is pressed! and when the application receives a
+)6'())AA$ message.
OnCommandHelp
HRESULT OnCo!!andHelp(lon) h(a!e-nd, lon) +HelpCo!!and, lon) nC!dID )

Solid Edge calls this method! passing in n'mdI$ whenever the user re4uests help or
an add-in command previously added to Solid Edge by the add-in. The value o the
add-in command identiier passed in will be one o the values the add-in gave the
application when it previously called the SetAddInIno method. I Solid Edge passes in
-E! the add-in should call help or the add-in in general #that is! not help or a speciic
command&.
The handle to the rame window! hBrame+nd as well as an indicator as to the type o
help #uDelp'ommand& is also passed in. These two parameters can be used in the
+inDelp call and valid values o uDelp'ommand are documented with the +inDelp
unction documentation.
'ote +hen a command bar button is added! the dispatch interace o the button is
returned. The interace contains help ilename and conte,t properties that can be set by
the add-in. I set! these properties are used to invo"e +inDelp directly rom Solid
Edge instead o calling (n'ommandDelp.
185
Chapter 24 Solid Edge Programmer's Guide
Working with Solid Edge Objects, Interfaces, and
Events
ISEAddIn
This interace is passed into the add-in8s (n'onnection method. The Solid Edge
ob*ects that implement this interace are created one per add-in when Solid Edge starts
up regardless o whether the add-in is loaded. These ob*ects represent the add-in within
Solid Edge. This same interace is e,posed by means o the application8s add-in8s
collection ob*ect. 1ecause this interace is e,posed to automation! some o the
unctions in the interace can only be called during the connection process! thus
ensuring that only the add-in itsel ma"es the calls.
Syntax Examples
To return the dispatch interace o the application2
HRESULT )et&Application( IDispatch **Application )

To return the I:n"nown o the connectable ob*ect that provides the
ISEAddInEvents and $ISEAddInEvents connection points2
HRESULT )et&AddInEvents( AddInEvents **AddInEvents )

To determine whether or not the add-in is connected. 'onnect is set to
/A<IAAT6T<:E i the add-in is connected otherwise /A<IAAT6BA%SE2
HRESULT )et&Connect( $ARIA%T&"OOL *Connect )

To programmatically connect to #/A<IAAT6T<:E& or disconnect rom
#/A<IAAT6BA%SE& the add-in2
HRESULT p+t&Connect( $ARIA%T&"OOL Connect )

To access a brie description o the add-in2
HRESULT )et&Desciption( "STR *Desciption )

To set a brie description o the add-in. The description should be internationaliCed
and also serves as the menu te,t o a tools pop-up menu that will be created i the
add-in adds any commands to an environment. The put6$escription can only be
called successully during initial connection2
HRESULT p+t&Desciption( "STR Desciption )
%ote. As o/ Solid Ed)e $esion 0, the Desciption stin) can 'e +sed to
indicate that the addin *ants its !en+ to appea on the top1level o/ the
Solid Ed)e !ain !en+ o as a pop1+p !en+ +nde one o/ the co!!on enties
othe than the tools !en+2 To )et a ne* ent3 on the top1level !en+, add a
ne* line chaacte (4n) to the 'e)innin) o/ the desciption2 The pop1+p
!en+ can 'e placed +nde one o/ the co!!on !en+ enties '3 concatenatin)
186
Working with Add-ins Chapter 24
one o/ the /ollo*in) stin)s (case insensitive) *ith the ne* line
chaacte and the desciption.
(ILE
EDIT
$IE-
-I%DO-
HEL#
TOOLS
(o e,a!ple, i/ the desciption is 5(ile4nM3 Addin6, the /ile !en+ *ill
contain a 5M3 Addin6 ent32 A desciption o/ 54nM3 Addin6 *ill es+lt in
the top1level !en+ containin) a 5M3 Addin6 ent32

To get the add-in8s guid in the string ormat deined by the +in API
StringBrom9:I$. The '%SI$BromString +in API can convert the string bac"
into its globally uni4ue identiier orm2
HRESULT )et&7UID( "STR *7UID )

To get the version o the add-in as it relates to the user interace changes it ma"es
in Solid Edge2
HRESULT )et&7+i$esion( lon) *7+i$esion )

To set the version o the add-in as it relates to the user interace changes it ma"es
in Solid Edge. An add-in that adds commands to any environment should always
set the version in (n'onnect. Solid Edge will persist this version when it shuts
down. (n subse4uent runs! a dierence in the last persisted version and the
version passed to put69ui/ersion will cause Solid Edge to purge any and all menu
entries and command bar buttons that were created and saved in the last session.
Also! when (n'onnectToEnvironment is called! bBirstTime will be set to
/A<IAAT6T<:E when a change in the version is detected2
HRESULT p+t&7+i$esion( lon) 7+i$esion )

To get the dispatch interace o the add-in i it e,ists. 1e sure to call <elease#&
when the interace is no longer needed2
HRESULT )et&O'8ect( IDispatch **O'8ect )

To set the dispatch interace o the add-in. Solid Edge will Add<e the ob*ect
when storing it and call <elease when it successully disconnects rom the add-in2
HRESULT p+t&O'8ect( IDispatch *O'8ect )

To access the program identiier o the add-in i it has one. Solid Edge will call
ProgI$Brom'%SI$ with the clsid o the add-in and return it as the string2
HRESULT )et&#o)ID( "STR *#o)ID )

187
Chapter 24 Solid Edge Programmer's Guide
To determine whether the add-in should appear in the list o add-ins presented to
the user or connection and disconnection by Solid Edge. Setting /isible to
/A<IAAT6BA%SE will also prevent the add-in rom being disconnected
programatically2
HRESULT )et&$isi'le( $ARIA%T&"OOL *$isi'le )

To prevent Solid Edge rom presenting the add-in in the list o add-ins presented to
the user or connection and disconnection and to prevent the add-in rom being
disconnected programatically! called with a value o /A<IAAT6BA%SE. Aote
that add-ins that set /isible to /A<IAAT6BA%SE ensure that the add-in will only
be disconnected at shutdown2
HRESULT p+t&$isi'le( $ARIA%T&"OOL $isi'le )

To call SetAddInInfo:
HRESULT SetAddInIn/o( lon) nInstanceHandle, "STR
EnvCatID, "STR Cate)o3%a!e,
lon) nIDColo"itMapReso+ceMedi+!,
lon) nIDColo"itMapReso+ceLa)e,
lon) nIDMonocho!e"itMapReso+ceMedi+!,
lon) nIDMonocho!e"itMapReso+ceLa)e,
lon) n%+!'eO/Co!!ands, SA(EARRA9 **Co!!and%a!es,
SA(EARRA9 **Co!!andIDs )

nInstanceHandle is the DIASTAA'E o the add-in8s resource $%%! cast to a
long.
EnvCatID is the category identiier o the environment to which commands are
being added.
CategoryName is a name that the add-in associates with the set o commands it is
adding to the environment. The name should be internationaliCed as it can be
presented to the user by Solid Edge.
nIDColorBitMapResourceMedium is the I$ o the bitmap resource containing
medium-siCed images o all the toolbar buttons that the add-in is adding.
nIDColorBitMapResourceLarge is the I$ o the bitmap resource containing
large-siCed images o all the toolbar buttons that the add-in is adding.
nIDMonochromeBitMapResourceMedium is the I$ o the bitmap resource
containing medium-siCed monochrome images o all the toolbar buttons that the
add-in is adding.
nIDMonochromeBitMapResourceLarge is the I$ o the bitmap resource
containing large-siCed monochrome images o all the toolbar buttons that the add-
in is adding.
nNumberOfCommands is the number o commands being added to the
environment.
188
Working with Add-ins Chapter 24
CommandNames is an array o 1ST<s. Each string can contain sub-strings
separated by @Fn@. The substrings are deined as ollows2
Aame o the command you are adding. This should not be internationaliCed
and should be tagged in such a way to help ensure uni4ueness.
Te,t displayed on the menu entry or the command. This substring may
contain bac"slash characters! which Solid Edge #/ersion G or later& will use to
create additional pop-up submenus and3or to add a separator preceding the
command entry #/ersion H or later&. The strings appearing between the
bac"slashes become the title o the pop-up menu and the last string becomes
the entry on the inal menu. I the irst character o any substring #including
the irst& is itsel a bac"slash! Solid Edge will add a separator preceding the
menu entry.
Status bar string. This is the string displayed on the status bar.
Tooltip string. This is the string displayed as the tooltip.
)acro string. I present! this string becomes the macro associated with the
command. 'ommands that have a macro string will not be invo"ed by calling
(n'ommand. Instead! Solid Edge runs the macro.
Parameter string. I present! this string is passed as an argument to the macro.
Eample!
:M3AddinCo!!and;4nSEaddin Sa!ple Co!!and4nDispla3s a !essa)e
'o,4nSeaddin Co!!and:

The non-internationaliCed tag or the command is @)yAddin'ommandE@.
@Seaddin Sample 'ommand@ will appear as an entry on the addin8s pop-up
menu created by Solid Edge. @$isplays a message bo,@ will appear in the
status ield o the rame window. @Seaddin 'ommand@ is displayed as the
tooltip or the command i it is added to a command bar by calling
Add'ommand1ar1utton.
Eample!
:M3AddinCo!!and;4nSEaddin4 Sa!ple Co!!and4nDispla3s a !essa)e
'o,4nSeaddin Co!!and:

This e,ample is identical to the one above with one e,ception. That being that
an additional pop-up submenu named @Seaddin@ will e,ist with @Sample
'ommand@ being an entry on that pop-up
Eample!
:M3AddinCo!!and;4nSEaddin44 Anothe Sa!ple Co!!and4nDispla3s a !essa)e
'o,4nSeaddin Co!!and:

189
Chapter 24 Solid Edge Programmer's Guide
This e,ample is identical to the one above with one e,ception. $ue to the
additional bac"slash! a separator will be inserted preceding the menu entry
@Another Sample 'ommand@.
CommandIDs on input is a pointer to a SABEA<<A- o identiiers the add-in is
to associate with each command being added. The add-in is ree to choose any
identiier it wishes. The command identiier chosen by the add-in is what is passed
in (n'ommand! (n'ommand:pdate:I and (n'ommandDelp.
'ommandI$s is also an output o SetAddInIno. +hen the unction returns! the
array contains the runtime command identiier Solid Edge has associated with the
command. This identiier is what the operating system will pass in the
+)6'())AA$ message. It can also be used to add a button or the command
using the @Add@ method available in the command bar controls8 automation
interace.
To call AddCommandBarButton:
HRESULT AddCo!!and"a"+tton( "STR EnvCatID, "STR Co!!and"a%a!e,
lon) nCo!!andID, Co!!and"a"+tton
**Co!!and"a"+tton )

EnvCatID is the category identiier o the environment to which a button is being
added.
CommandBarName is the name o the command bar the button will be added to.
Solid Edge will create the command bar i it does not e,ist.
nCommandID is any o the command identiiers the add-in passed to
SetAddInIno #not the identiier passed bac" rom Solid Edge&.
CommandBarButton is the dispatch interace o the button ob*ect that provides
or additional programming capabilities. The v-table e4uivalent interace!
ISE'ommand1ar1utton can be obtained by 4uerying the returned ob*ect or
II$6ISE'ommand1ar1utton. Bor e,ample! i the add-in wants to have Solid Edge
invo"e +inDelp or the command! it can set the help ilename and help conte,t
properties.
Add'ommand1ar1utton is used by the add-in to have Solid Edge display a button
or the command. This routine only needs to be called i the
(n'onnectToEnvironment argument! bBirstTime is /A<IAAT6T<:E. Aote that
this method can be called anytime #that is! Solid Edge does not restrict calls to this
routine to emanate rom the add-in8s (n'onnectToEnvironment method&. 1uttons
can also be added via the command bar automation interaces but there are
advantages to using this method.
Solid Edge will create the command bar i it does not e,ist.
Solid Edge can maintain the relationship between the button and the add-in. This
allows Solid Edge to remove such buttons when the add-in is disconnected or i in
subse4uent startups! the add-in no longer e,ists because it has been uninstalled by
the user. It also allows Solid Edge to purge old commands i the 9:I version o
the add-in has changed.
190
Working with Add-ins Chapter 24
(ne unction call as opposed to the many calls needed to add a button via the
automation interaces.
'ote Always be sure to <elease the returned 'ommand1ar1utton interace.
An add-in can set its 'ommand1ar1utton (nAction properties #and
ParameterTe,t& to a valid Solid Edge @macro@ and not connect up to the AddIn
event set to listen or (n'ommand. +hen the user selects the command! Solid
Edge uses its @<un )acro@ subsystem to run the command.
191
Chapter 24 Solid Edge Programmer's Guide
Eample!
OnAction < :notepad2e,e :
#aa!eteTe,t < :test2t,t:

Pressing a button with these properties and added by an add-in that is not
connected to the AddIn event set will cause Solid Edge to launch Aotepad with
@test.t,t@ as the ile or Aotepad to open.
To call AddCommand:
:se this method instead o SetAddInIno or those commands without a 9:I that goes
with it #that is! there are no command bar buttons&.
HRESULT AddCo!!and( "STR EnvCatID, "STR C!d%a!e, lon) lCo!!andID)

EnvCatID is the category identiier o the environment to which a command is
being added.
CmdName is a string that contains sub-strings separated by a new line character
#8Fn8&. In order! the substrings are2
Aame o the command you are adding. This should not be internationaliCed and
should be tagged in such a way to help ensure uni4ueness.
Te,t displayed on the menu entry or the command. This substring may contain
bac"slash characters! which Solid Edge #/ersion G or later& will use to create
additional pop-up submenus and3or to add a separator preceding the command
entry #/ersion H or later&. The strings appearing between the bac"slashes become
the title o the pop-up menu and the last string becomes the entry on the inal
menu. I the irst character o any substring #including the irst& is itsel a
bac"slash! Solid Edge will add a separator preceding the menu entry.
Status bar string. This is the string displayed on the status bar.
Tooltip string. This is the string displayed as the tooltip.
)acro string. I present! this string becomes the macro associated with the
command. 'ommands that have a macro string will not be invo"ed by calling
(n'ommand. Instead! Solid Edge runs the macro.
Parameter string. I present! this string is passed as an argument to the macro.
E,ample2
:M3AddinCo!!and;4nSEaddin Sa!ple Co!!and4nDispla3s a !essa)e 'o,4nSeaddin
Co!!and:

The non-internationaliCed tag or the command is @)yAddin'ommandE@.
@Seaddin Sample 'ommand@ will appear as an entry on the addin8s pop-up menu
created by Solid Edge. @$isplays a message bo,@ will appear in the status ield o
the rame window. @Seaddin 'ommand@ is displayed as the tooltip or the
command i it is added to a command bar by calling Add'ommand1ar1utton.
192
Working with Add-ins Chapter 24
E,ample2
:M3AddinCo!!and;4nSEaddin4 Sa!ple Co!!and4nDispla3s a !essa)e 'o,4nSeaddin
Co!!and:

This e,ample is identical to the one above with one e,ception. That being that an
additional pop-up submenu named @Seaddin@ will e,ist with @Sample 'ommand@
being an entry on that pop-up
E,ample2
:M3AddinCo!!and;4nSEaddin44 Anothe Sa!ple Co!!and4nDispla3s a !essa)e
'o,4nSeaddin Co!!and:

This e,ample is identical to the one above with one e,ception. $ue to the
additional bac"slash! a separator will be inserted preceding the menu entry
@Another Sample 'ommand@.

lCommandID is the inde, used by Solid Edge to identiy to the add-in which
command is being invo"ed when Solid Edge calls the (n'ommand!
(n'ommand:pdate:I and (n'ommandDelp events.
ISECommandDISECommand
+hen the application8s 'reate'ommand method is called! it returns the
$ISE'ommand dispatch interace o an ob*ect #that can be 4ueried or ISE'ommand
using II$6ISE'ommand to get its e4uivalent v-table interace&. The properties and
methods are as ollows2
)ouse.<ead-only property that returns the $ISE)ouse interace ob*ect #which
can be 4ueried or ISE)ouse using II$6ISE)ouse to get its e4uivalent v-table
interace& o the mouse control. The ob*ect that implements the interace is also a
connectable ob*ect that provides the $ISE)ouseEvents and ISE)ouseEvents
event sets.
'ommand+indow.<ead-only property that returns the I:n"nown interace o a
connectable ob*ect that provides the $ISE'ommand+indowEvents and
ISE'ommand+indowEvents event sets.
$one.<ead-write 1oolean property used to notiy Solid Edge that the command
is inished and is to be terminated. 'ommands that are created with the
seTerminateAterActivation setting do not have to set this property as they will be
terminated ater Activate is called. (ther commands should set this property when
their command is inished. The initial #deault& value is BA%SE.
(nEdit(wner'hange.<ead-write %ong property used to notiy Solid Edge that
the command is to be terminated whenever an edit owner change occurs.
'ommands that set this variable will be relieved o undo transaction calls.
'ommands that modiy multiple edit owners #or e,ample! multiple documents&
193
Chapter 24 Solid Edge Programmer's Guide
should set this lag to Cero. In such cases! it is up to the command to ma"e any
necessary undo transaction calls using the automation interaces.
(nEnvironment'hange.<ead-write %ong property used to notiy Solid Edge that
the command is to be terminated whenever an environment change occurs.
Start.'all this method ater creating the command and connecting to the
command event set. Ater Start is called and control is returned to Solid Edge! the
command! its mouse and window will start sending events to the add-in or
processing.
'ote To receive the Activate! $eactivate and Terminate events! the add-in must
connect up to the command event set beore calling Start.
ISECommandEventsDISECommandEvents
The ob*ect returned rom 'reate'ommand provides these event sets. The add-in
command will normally provide this event sin" and connect the sin" to the ob*ect
ac4uired by calling 'reate'ommand. The ob*ect passed in implements
II$6I'onnectionPoint'ontainer so the command can connect the sin" using the
standard '() connection point interaces #don8t orget to Advise3:nadvise&. The
member unctions o this sin" are as ollows2
Activate#&.Activates the command.
$eactivate#&.$eactivates the command. Either the user has terminated the
command or has invo"ed another command #that is! the command is being
stac"ed&. At this point! i the command has any modal dialog bo,es displayed! it
should undisplay them until Activate is called.
Terminate#&.Aotiies the command that it is being terminated.
Idle# long l'ount! %P1((% pb)ore &.Aotiies the command that idle cycles are
available. l'ount represents the number o cycles that have occurred. The
command can set pb)ore to BA%SE in which case Solid Edge will not give the
command any more idle cycles. I a command does not perorm any idle
processing! it should set this to BA%SE.
7ey$own# unsigned short I 7ey'ode! short Shit &.Aotiies the command o a
"ey down event. The "eycode and a shit indicator is passed into this method.
7eyPress# unsigned short I 7eyAscii &.Aotiies the command o an AS'II "ey
press event. The AS'II character is passed into this method.
7ey:p# unsigned short I 7ey'ode! short Shit &.Aotiies the command o a "ey
up event. The "eycode and a shit indicator is passed into this method.
Aote that the dierence between 7ey$own and 7eyPress is subtle. 7ey$own occurs
whenever any "ey is pressed while 7eyPress occurs only when an AS'II "ey is
pressed. Also be aware that both o these events @repeat@ as long as the user continues
to "eep a "ey pressed.
Examples:
194
Working with Add-ins Chapter 24
The user presses and releases the SDIBT "ey. Solid Edge sends the command a
7ey$own event ollowed by a 7ey:p event.
The user presses and releases the EATE< "ey. Solid Edge sends the command a
7ey$own event! a 7eyPress! and then a 7ey:p event! in that order.
The user presses the BE "ey and continues to hold the "ey down. Solid Edge sends
the command a series o 7ey$own events until the user releases the "ey! at which
time Solid Edge sends a 7ey:p event.
The user presses the number J "ey and continues to hold the "ey down. Solid Edge
sends the command a series o 7ey$own and 7eyPress events until the user
releases the "ey! at which time Solid Edge sends a 7ey:p event.
ISE!ouseDISE!ouse
This is the interace returned rom the command8s )ouse property. This interace is
used by the add-in command to get and set certain properties used by Solid Edge to
help the add-in command manage mouse events. This includes the capability to speciy
various Solid Edge locate modes and to set locate ilters that enable the add-in
command to speciy what types o ob*ects should be located.
The properties o this interace are as ollows2
Scale)ode.<ead-write %ong value. Setting Scale)ode to K implies that
coordinates o the mouse events are in the underlying window coordinate system
and E implies that they are in design modeling coordinate system.
Enabled)ove.<ead-write 1oolean that! i set to True! causes )ove and $rag in
progress events to be ired.
%astEvent+indow.<ead-only. <eturns the dispatch interace o the window
ob*ect in which the last mouse event occurred.
%ast:pEvent+indow.<ead-only. <eturns the dispatch interace o the window
ob*ect in which the last mouse up event occurred.
%ast$ownEvent+indow.<ead-only. <eturns the dispatch interace o the
window ob*ect in which the last mouse down event occurred.
%ast)oveEvent+indow.<ead-only. <eturns the dispatch interace o the
window ob*ect in which the last mouse move event occurred.
%astEventShit.<ead-only Short that is the state o the 'T<%! A%T! and SDIBT
"eys when the last mouse event occurred. /alid values are those enumerated by
the se7ey constants.
%ast:pEventShit.<ead-only Short that is the state o the 'T<%! A%T! and
SDIBT "eys when the last mouse up event occurred. /alid values are those
enumerated by the se7ey constants.
195
Chapter 24 Solid Edge Programmer's Guide
%ast$ownEventShit.<ead-only Short that is the state o the 'T<%! A%T! and
SDIBT "eys when the last mouse down event occurred. /alid values are those
enumerated by the se7ey constants.
%ast)oveEventShit.<ead-only Short that is the state o the 'T<%! A%T! and
SDIBT "eys when the last mouse move event occurred. /alid values are those
enumerated by the se7ey constants.
%astEvent1utton.<ead-only Short that indicates which button the last mouse
event occurred on. /alid values are those enumerated by the se1utton constants.
%ast:pEvent1utton.<ead-only Short that indicates which button the last mouse
up event occurred on. /alid values are those enumerated by the se1utton
constants.
%ast$ownEvent1utton.<ead-only Short that indicates which button the last
mouse down event occurred on. /alid values are those enumerated by the se1utton
constants.
%ast)oveEvent1utton.<ead-only Short that indicates which button the last
mouse move event occurred on. /alid values are those enumerated by the se1utton
constants.
%astEvent5.<ead-only $ouble that is the 5 coordinate o the mouse when the
last mouse event occurred.
%astEvent-.<ead-only $ouble that is the - coordinate o the mouse when the
last mouse event occurred.
%astEventL.<ead-only $ouble that is the L coordinate o the mouse when the
last mouse event occurred.
%ast:pEvent5.<ead-only $ouble that is the 5 coordinate o the mouse when the
last mouse up event occurred.
%ast:pEvent-.<ead-only $ouble that is the - coordinate o the mouse when the
last mouse up event occurred.
%ast:pEventL.<ead-only $ouble that is the L coordinate o the mouse when the
last mouse up event occurred.
%ast$ownEvent5.<ead-only $ouble that is the 5 coordinate o the mouse when
the last mouse down event occurred.
%ast$ownEvent-.<ead-only $ouble that is the - coordinate o the mouse when
the last mouse down event occurred.
%ast$ownEventL.<ead-only $ouble that is the L coordinate o the mouse when
the last mouse down event occurred.
%ast)oveEvent5.<ead-only $ouble that is the 5 coordinate o the mouse when
the last mouse move event occurred.
%ast)oveEvent-.<ead-only $ouble that is the - coordinate o the mouse when
the last mouse move event occurred.
196
Working with Add-ins Chapter 24
%ast)oveEventL.<ead-only $ouble that is the L coordinate o the mouse when
the last mouse move event occurred.
+indowTypes.<ead-write %ong which! i set to K! implies that mouse events
emanate rom all windows. I set to E! +indowTypes implies that mouse events
emanate only rom graphic windows.
%astEventType.<ead-only %ong that returns the last mouse event type. /alid
values are those enumerated by the se)ouseAction constants.
Enabled$rag.<ead-write /A<IAAT61((% that i set to /A<IAAT6T<:E
causes drag events to be ired.
%ocate)ode.<ead-write %ong that indicates how to locate2 K implies
Smart)ouse locate! E implies simple clic" locate #no multi-select dialog&! 2
implies 4uic" pic" locate #multi-select dialog where applicable& and M implies no
locate #used to receive mouse events without perorming any locate&. Bor simple
and 4uic" pic" locate modes! users will be able to mouse down! drag and mouse
up or ence locate. This property is applicable when a mouse service ob*ect is
registered.
$ynamics)ode.<ead-write %ong that speciies which shape to draw in
dynamics2 K implies o! E implies line! 2 implies circle! M implies rectangle.
Pause%ocate.<ead-write %ong that speciies how long in milliseconds to wait
beore a locate occurs. :se this property when you don8t want to locate during
mouse moves but do want to locate as the mouse pauses or hesitates.
The methods o this interace are as ollows2
'lear%ocateBilter#&.'lears the locate ilter. I the locate mode is not
se%ocate(! clearing the ilter enables all ilters.
AddTo%ocateBilter.<estricts locates to the graphic types speciied. /alid values
are those enumerated by the se%ocateBilter'onstants constants.
197
Chapter 24 Solid Edge Programmer's Guide
ISE!ouseEventsDISE!ouseEvents
The command8s )ouse property also supports these event sets. Add-in commands that
are interested in mouse events! including locate capability! will normally provide one
o these event sin"s and connect the sin" to the )ouse. The )ouse implements
I'onnectionPoint'ontainer so the command can connect the sin" using the standard
'() connection point interaces #be sure to Advise3:nadvise&. +hen a command is
in a state where it does not want to process mouse events or perorm locates! it can
:nadvise this sin" until such time it re4uires those events! in which case it can call
Advise again. Aote that there is no limit to the number o connections attached to this
connection point. Dowever! be aware that there is only one set o properties that
control the behavior o this sin". The member unctions o this sin" are as ollows2
)ouse$own.This event is sent whenever the user presses a mouse button down.
1utton and Shit are identical to those used in the mouse property events.
Mo+seDo*n( shot s"+tton, shot sShi/t,
do+'le d=, do+'le d9, do+'le d>,
L#DIS#ATCH p-indo*Dispatch, lon) l?e3#ointT3pe,
L#DIS#ATCH p7aphicDispatch )

)ouse:p.This is the same as the )ouse$own event e,cept that it is sent
whenever a mouse up event occurs.
)ouse)ove.This is the same as the )ouse$own event e,cept that it is sent
whenever a mouse move event occurs.
)ouse'lic".This is the same as the )ouse$own event e,cept that it is sent
whenever a mouse clic" event occurs.
)ouse$bl'lic".This is the same as the )ouse$own event e,cept that it is sent
whenever a mouse double clic" event occurs.
)ouse$rag.This event is sent whenever the user presses a mouse button down.
1utton and Shit are identical to those used in the mouse property events. See the
se)ouse$ragState'onstants constants or values or the drag state.
Mo+seDa)( shot s"+tton, shot sShi/t,
do+'le d=, do+'le d9, do+'le d>,
L#DIS#ATCH p-indo*Dispatch, ,
shot Da)State, lon) l?e3#ointT3pe,
L#DIS#ATCH p7aphicDispatch ) 1

+hen a mouse clic" occurs in a Solid Edge window! the $own! :p! and then 'lic"
events are ired to the add-in command. 'orrespondingly! when a mouse double clic"
occurs the $own! :p! 'lic"! $ouble 'lic"! and then :p events are ired. I enabled!
drag events are ired when the mouse moves with a mouse button down. %et8s ta"e the
case where the user clic"s a button! moves the mouse with the button down! and then
releases the button. In this case the ollowing our possibilities e,ist2
198
Working with Add-ins Chapter 24
Enabled
Drag
Enabled
Move
Events #ired on the Mouse control
'ase E Balse Balse $own! :p! 'lic"
'ase 2 Balse True $own! )ove! ... )ove! :p! 'lic"
'ase M True Balse $own! $rag #State = Enter&! $rag #State = %eave&
'ase 4 True True $own! $rag #State = Enter&! $rag #State = In
progress&! N! $rag #State = In progress&! $rag
#State = %eave&
Eort is made to ensure that the mouse events are ired in se4uence. To do this when a
mouse down event occurs! the mouse input is loc"ed to the window in which the down
event occurred. +hen the corresponding mouse up event occurs! the loc" is removed.
This se4uence ensures that the add-in command will always receive a mouse up event
ater receiving a mouse down event. 1ecause the mouse up event will occur in the
same window as the down event! this implies that it is not possible to drag across
windows.
ISECommand"indo#EventsDISECommand"in
do#Events
The command8s +indow property supports these event sets. Add-in commands that
are interested in generic window events! including any registered private window
messages #see the +indow8s API! <egister+indow)essage& will want to provide this
event sin" and connect the sin" to the 'ommandOs +indow property ob*ect. The ob*ect
passed in implements I'onnectionPoint'ontainer so the command can connect the sin"
using the standard '() connection point interaces #be sure to Advise3:nadvise&.
+hen a command is in a state where it does not want to process window events! it can
:nadvise this sin" until such time it re4uires those events! in which case it can call
Advise again. Aote that there is no limit to the number o connections attached to this
connection point. The member unctions o this sin" are as ollows2
-indo*#oc( IDispatch* pDoc, IDispatch p$ie*, UI%T nMs),
-#ARAM *#aa!, L#ARAM l#aa!, LRESULT *lRes+lt )

Aote that this unction is analogous to the standard +indowProc unction used by
+indow applications everywhere. The main dierence is the dispatch pointers and the
%<ES:%T passed into it. The reason the %<ES:%T e,ists is that this unction is a
member o a '() interace and hence must return an D<ES:%T. Since +indowProc
unctions normally return a value whose value and meaning is determined by the n)sg
argument! this argument has been added and serves the same purpose.
An e,ample o why an add-in may want to implement this sin" is to ta"e advantage o
the +)6SET':<S(< message. Bor more inormation on that message! and what the
199
Chapter 24 Solid Edge Programmer's Guide
value o %<ES:%T means to the caller o this event unction! see the +indow8s
documentation or +)6SET':<S(<.
ISolidEd$eBar
This interace can be used by an add-in to insert a page into the Solid Edge Edgebar
tool. The Edgebar is available starting with /ersion H. The pages that e,ist on the
Edgebar tool are always document-speciic. That means that a page added to the
Edgebar or one document! will not appear on the Edgebar or any other document. In
order to obtain the Edgebar interace! 4uery the AddIn interace passed into the
ISolidEdgeAddIn22(n'onnection method using II$6ISolidEdge1ar. (nce obtained!
the interace can be used to add a page to the Edgebar! remove a previously added
page rom the Edgebar! and to set the active page o the Edgebar to one that has been
added.
Add%a$e
AddPage is called to add a page to the Edgebar tool or the document passed in. The
D+A$ passed bac" can be used in +indows APIs. Bor /isual '00 users this handle
can also be used! or e,ample! to create a '+nd ob*ect that can be used as the parent
o a '$ialog ob*ect that may be positioned inside the client area o the returned page.
HRESULT Add#a)e( IDispatch *theDoc+!ent, lon) nInstanceHandle,
lon) n"it!apID, "STR stTooltip, lon) nOption,
lon) *h-nd#a)e)

theDocument is the dispatch interace o the document or which the page is being
added.
nInstanceHandle is DIASTAA'E o the add-in8s resource $%%! cast to a long! in
which the bitmap resides.
nBitmapID is the resource identiier o the bitmap that will appear on the added
page8s tab. The bitmap dimensions should be 2K by 2K.
s$tr%ootip is a string which appears as a tooltip or the user when the cursor is
passed over the page8s bitmap.
nOption indicates which options the page wants. The options available are
enumerated by Edge1ar'onstant located in the Solid Edge constants typelib. A
value o Cero is valid and indicates no option. +hen this document was written!
the only available option indicates that resiCe events are not needed. Dence! Cero
indicates that resiCe events are needed.
h&nd'age is the D+A$ o the added page and is returned by Solid Edge to the
caller. The handle can be used to! or e,ample! to draw items on the page.
200
Working with Add-ins Chapter 24
&emove%a$e
Re!ove#a)e( IDispatch *theDoc+!ent, lon) h-nd#a)e, lon) nOptions )

theDocument is the dispatch interace o the document or which the page is being
removed.
h&nd'age is the D+A$ o the page being removed.
nOption indicates which options are needed. This argument is not currently
supported; set n(ption to Cero.
SetActive%a$e
SetActive#a)e(IDispatch *theDoc+!ent, lon) h-nd#a)e, lon) nOptions )

theDocument is the dispatch interace o the document or which the page is being
activated.
h&nd'age is the D+A$ o the page being activated.
nOption indicates which options are needed. This argument is not currently
supported; set n(ption to Cero.
ISolidEd$e&i''onBar
This interace can be obtained rom the ISE'ommand interace and provides an add-in
command with ribbon bar capability. The ribbon bar interace or an add-in command
is available starting with version P o Solid Edge.
&i''on Bar Arc(etecture
To the user! the ribbon bar appears to be a single component. In actuality it is
composed o two entities. (ne is a dialog bo, and the other is essentially a dialog bo,
holder. Solid Edge provides the holder! which ta"es care o doc"ing the ribbon bar as
well as providing other common unctionality such as resiCing o any buttons on the
dialog bo,. The holder also provides a mechanism that allows or the deinition o
"eyboard accelerators and command deined Qedit ieldsR that can be used to assist the
user with control navigation. The command writer supplies the actual dialog bo, and
the list o accelerators and edit ields. Since the add-in command writer will not need
to be concerned with the holder component! rom here on! I will normally use the terms
Qdialog bo,R and Qribbon barR interchangeably.
The ribbon bar is command speciic in that it is only associated with a single
command. The lie o the ribbon bar is controlled by the lie o the command. +hen
the command is terminated! its ribbon bar is destroyed. Its actual destruction is the
responsibility o the ob*ect behind the ISE'ommand interace. That ob*ect also is
responsible or displaying and undisplaying the dialog bo, at appropriate times. Bor
e,ample! i an add-in command receives a $eactivate event! it does not have to worry
about undisplaying the ribbon bar.
201
Chapter 24 Solid Edge Programmer's Guide
&i''on Bar Desi$n Considerations
+hen designing a ribbon bar! the designer should create a dialog bo, that is 2E dialog
units high. Solid Edge does not mandate the width o the dialog bo,. The dialog bo,
can contain any number o controls such as buttons! pictures and combo bo,es. +hen
a command adds a ribbon bar to the Solid Edge 9:I! it will provide Solid Edge with
both the dialog bo, identiier and the handle to the dll that contains the dialog bo,
resource.
The dialog bo, holder component o the ribbon bar tries to minimiCe the space that the
dialog bo, component o the ribbon bar uses. This QeatureR can alleviate the designer
rom worrying about some o the design o! or e,ample! the spacing between buttons.
It can also be a headache when it comes to designing the dialog bo, in that the bo,
may appear dierently in a resource editor than it does when it is added to the 9:I
using the ribbon bar interace. I have ound that a tric" can be pulled on the holder in
order to maintain a common loo" between your avorite resource editor and the ribbon
bar once Solid Edge displays it. The tric"S Add an empty static te,t bo, between
controls that you want to remain separated when displayed to the userT
%rocessin$ User Input
'ontrols on a dialog bo, normally communicate with the dialog bo, by sending it
messages. All such messages are orwarded to the add-in command using the
+indowProc event member o the ISE'ommand+indowEvents interace. The e,act
nature o the message sent to a dialog bo, rom any control depends on the control.
)any o the common controls that e,ist send +)6'())AA$ messages to the
dialog bo,. Bor e,ample! buttons send this message with the wParam being the
buttonOs identiier while combo bo,es send +)6'())AA$ messages with the hi
word o wParam containing the notiication message and the lo word o wParam
containing the control identiier. Bor individual controls! see >+in:ser.h? or consult
the )S$A or other documentation that e,ists or the control in order to determine
e,actly how the control notiies its parent #i.e.! your dialog bo,&.
Add&i''on
D<ES:%T Add<ibbon# int $ialogId! long InstanceDandle! long Ih+nd<ibbon &
$ialogId U This is the resource identiier o the dialog bo,
InstanceDandle U This is the handle to the resource dll that contains the dialog
bo,
D+nd<ibbon U This is the handle to the dialog bo, window.
Add<ibbon is called to attach a dialog bo, to the ribbon bar holder.
<eturn value
S6(7 indicates that the dialog bo, was successully retrieved rom the resource ile.
202
Working with Add-ins Chapter 24
<emar"s
An add-in command can call Add<ibbon at any time during its lie cycle. It can also
call Add<ibbon multiple times. I Additional calls to Add<ibbon are made! the current
ribbon bar! i it e,ists! will be destroyed.
$o A(T destroy the returned window handleTT Solid Edge ta"es care o destroying the
window whenever the command is terminated! a subse4uent call to <emove<ibbon is
made or another call to Add<ibbon is made.
SetCurrent)ocus
D<ES:%T Set'urrentBocus#&
'all Set'urrentBocus to set the ocus to the ribbon bar.
<eturn
S6(7 i ocus was set to the ribbon bar.
<emar"s
Set'urrentBocus also will orce ocus to be set to the irst control in the edit ield list
i the ribbon bar does not currently have ocus.
I a ribbon bar is added beore the command is activated! there is no need to call
Set'urrentBocus when the command is activated.
In rare cases! there can actually be more than one ribbon bar presented to the user.
The Solid Edge $rat environment has a S"etchPoint command which does *ust this.
In such cases! you may ind it necessary to call Set'urrentBocus in the Idle event
handler since the user can manually switch ocus to the other ribbon bar. Bailure to do
so can result in the loss o accelerator messages.
S(o#&i''on
D<ES:%T Show<ibbon#&
Show<ibbon is called to display the ribbon bar.
<eturn value
S6(7 indicates that the ribbon bar was successully displayed.
<emar"s
As long as Dide<ibbon has not been called! the ob*ect that provides the ISE'ommand
interace displays the ribbon whenever the command is activated. Dence! Show<ibbon
would only need to be called i the command calls Add<ibbon beore being activated
or has called Dide<ibbon. There is no harm done i Show<ibbon is called while the
ribbon bar is already displayed.
Hide&i''on
203
Chapter 24 Solid Edge Programmer's Guide
D<ES:%T Dide<ibbon#&
Dide<ibbon is called to undisplay the ribbon bar or to prevent the ob*ect that provides
the ISE'ommand interace rom providing deault display behavior o the ribbon bar.
<eturn value
S6(7 indicates that the ribbon bar was undisplayed.
<emar"s
'all Dide<ibbon to "eep the ribbon bar rom being displayed when the initial
activation o the add-in command occurs. I Dide<ibbon is called! the ribbon bar will
not be displayed during command activation unless and until Show<ibbon is called.
There is no harm done i Dide<ibbon is called while the ribbon bar is not displayed! or
even i the ribbon bar does not e,ist.
&emove&i''on
D<ES:%T <emove<ibbon#&
'all <emove<ibbon to destroy the ribbon bar.
<eturn value
S6(7 i the ribbon bar was removed.
<emar"s
(nce <emove<ibbon is called! the handle to the ribbonOs window is destroyed and
hence the handle previously returned rom Add<ibbon is invalid. There is no need to
call <emove<ibbon when the command itsel is being terminated. Also! there is no
need to irst call <emove<ibbon i a ribbon already e,ists and the command is calling
Add<ibbon.
AddEdit)ield
D<ES:%T AddEditBield# int 'ontrolId &
'ontrolId U The identiier o a control on the ribbon bar being deined as an
edit ield.
'all AddEditBield to add a control to the ribbon bar holderOs list o edit ields.
<eturn value
S6(7 indicates that the control was added to the list.
<emar"s
204
Working with Add-ins Chapter 24
The control identiier is the identiier o a control on the dialog bo,.
The order controls are added to the list o edit ields deines the navigation se4uence
that occurs during calls to Ae,tBocus. Aormally edit controls and rich edit controls
would be candidates to be added as edit ields #hence the name AddEditBield&.
<esponding to the 7ey$own command event in order to detect return3enter "eyboard
events and then calling Ae,tBocus to automatically move ocus to another edit ield on
the ribbon bar can accomplish navigation! or e,ample.
+hen the initial display o the ribbon bar occurs! the irst control added to the list o
edit ields will be given ocus.
E,ample
33 See i this is the @return3enter@ "ey. I so! see which control has the ocus on the
33 ribbon bar. 'ontrols added as an @edit ield@ using the AddEditBield member
33 unction o the ribbon bar interace deine a ocus list. Bocus can be moved rom
33 one control to another by caling Ae,tBocus. This sample does *ust that whenever
33 the user hits enter.
i# K,d == I7ey'ode &
V
int id;
p<ibbon1ar-?9et'urrentBocus#Wid&;
33 9et'urrentBocus returns -E i the control with the ocus is not in the list o
33 @edit@ ields added by calling AddEditBield. In that case! I don8t bother to
33 move the ocus.
i# -E T= id &
V
p<ibbon1ar-?Ae,tBocus#&;
X
*etCurrent)ocus
D<ES:%T 9et'urrentBocus# intI 'ontrolId &
'ontrolId U The identiier o the edit ield that currently has ocus or UE i no
edit ield in the edit ield list currently has ocus.
205
Chapter 24 Solid Edge Programmer's Guide
9et'urrentBocus is called to determine whether a control in the list o controls
currently has ocus.
<eturn value
S6(7 or E6P(IATE< i the input 'ontrolId pointer is A:%%.
<emar"s
This routine only returns control identiiers that have been added to the list o edit
ields by calling AddEditBield.
+ext)ocus
D<ES:%T Ae,tBocus#&
'all Ae,tBocus to move ocus to rom the current edit ield that has ocus to the ne,t
edit ield.
<eturn value
S6(7 i ocus was moved to the ne,t edit ield.
<emar"s
The ne,t edit ield is deined by the position o the current edit ield in the list o edit
ields. I no edit ield in the list o edit ields currently has the ocus! ocus is moved to
the irst edit ield in the list.
SetAccelerators
D<ES:%T SetAccelerators# SABEA<<A-#char& IIAccelerators &
Accelerators U Array o characters that are used to provide "eyboard
acceleration or the user
'all SetAccelerators to deine "eys that can be used to provide a "eyboard interace
or certain unctionality on the ribbon bar.
<eturn value
S6(7 i the accelerators were installed.
<emar"s
+henever the user pushes a "ey down that has been added to the list o accelerators!
the add-in command will receive a message in its
ISE'ommand+indowEvents22+indowProc event handler. The value o the message
will be se+)6A''E%E<AT(<SE%E'TE$ #deined in the constants typelib& and
the wParam will contain the character.
E,ample
33 $eine an accelerator or the ribbon bar
206
Working with Add-ins Chapter 24
SABEA<<A- IAccelerators;
SABEA<<A-1(:A$ Accelerators1ound;
Accelerators1ound.l%bound = K;
Accelerators1ound.cElements = E;
char , = 8o8;
Accelerators = SaeArray'reate#/T6IE! E! WAccelerators1ound &;
long inde, = K;
hr = SaeArrayPutElement#Accelerators! Winde,! #voidI&W,&;
p<ibbon1ar-?SetAccelerators# WAccelerators &;
33 %ater that day in the +indowProc event handler N
switch# n)sg &
case se+)6A''E%E<AT(<SE%E'TE$2
char "ey = wParam;
i# "ey == 8o8 & T<A'E# @o accelerator hitFn@ &;
brea";
Additional Solid Ed$e o',ects- interfaces and
events
Additional Solid Edge ob*ects! interaces and event sets are obtainable by means o the
automation interace pointers #the I$ispatch pointers passed into any o the add-in8s
event sin"s or interaces&. These interaces are not directly related to the add-in
system. They are generic automation related interaces and thus are documented by the
Solid Edge S$7.
207
Chapter 24 Solid Edge Programmer's Guide
Registering an Add-in
Bor Solid Edge to "now there is an add-in registered or use with it! the add-in needs to
add the @Implemented 'ategories@ sub"ey in the registry and add the 9:I$ or
'ATI$6SolidEdgeAddIn.
Solid Edge also deines a set o categories that are used to indicate which
environment#s& an add-in is designed or. These categories are not directly supported
by the 'ategory )anager #the '()-supplied I'atInormation interace&. Solid Edge!
however! will search or an additional "ey! the @Environment 'ategories@ "ey! which is
much li"e the @Implemented3<e4uired 'ategories@ "eys supported by the 'ategory
)anager. Add-ins will enumerate as sub"eys to that "ey! any Solid Edge environment
or which the add-in plans to add commands and3or events. An add-in must implement
at least one o these categories.
The ollowing categories identiy what environments an add-in is designed or2
4. 'ATI$6SEApplication
%. 'ATI$6SEAssembly
&. 'ATI$6SEPart
7. 'ATI$6SEProile
". 'ATI$6SESheet)etal
In addition to registering the '() ob*ect that represents the add-in! which includes
not only the normal registry entries that the )icrosot 'omponent (b*ect )odel
speciies! but also the component categories the add-in implements! there are a ew
other registry entries that Solid Edge re4uires the add-ins to register. These entries will
be the values or sub"eys o the classid "ey o the add-in classid registered in the
D7E-6'%ASSES6<((TF'%SI$ registry entry. 'urrently! the entries and their
meanings are as ollows2
Automatic connection indicator . This value name should be @Auto'onnect@ and
the type should be a $+(<$. Set the value to E or now.
%ocaleI$ . The value name should be a )icrosot deined locale id and the type
should be a string. The string should contain a locale speciic description o the
add-in. E,ample2 @4KP@ #which identiies the locale as :.S. English& and @)y
company8s Solid Edge Add-in@. The id should be stored in he,adecimal ormat.
Bor more inormation on locale ids #also "nown as %'I$s&! see the )icrosot
documentation concerning locales.
In addition to the previously described registry entries! Solid Edge /ersions H and
greater loo" or additional registry entries. These are used by the Add-In )anager #as
is the original %ocaleI$ value string already registered&.
Summary.The "ey name should be @Summary!@ and it should contain the
ollowing2
%ocaleI$.The value name should be a )icrosot deined locale id #or
e,ample! 4KP&! and the type should be a string. The string should contain a
208
Working with Add-ins Chapter 24
locale-speciic summary o the add-in. The summary string will be presented
to the user upon invocation o the Solid Edge Add-In )anager. This entry is
analogous to the add-in8s description mentioned above. The id should be stored
in he,adecimal ormat.
Delp.The "ey name should be @Delp@ and it should contain the ollowing2
%ocaleI$.This named value is a string. The name o the value is the he,
value o the userOs locale identiier. The string is the name o the localiCed
help ilename. The help ile can be invo"ed by the user via the Solid Edge
Add-In )anager8s 9:I. E,ample2 4KP Qaddin.hlpR
'onte,t U This named value is a $+(<$. The value is the conte,t identiier
o where the Solid Edge Add-In )anager should open the help ile to i the
user selects the add-in help button on its dialog bo,.
Topic U This named value is a string. I the help ile is a html help ile! the
value o the string is the name o the htm page in the help ile the Solid Edge
Add-In )anager should open the help ile to i the user selects the add-in help
button on its dialog bo,.
Aote that the Add-In )anager irst loo"s or the 'onte,t value and only i it does
not e,ist does it loo" or the Topic value. I neither e,ist! the help ile is opened to
its deault page.
In order or Solid Edge to invo"e help on an add-in! the path to the add-inOs help
ile needs to be "nown. +hen Solid Edge invo"es +inDelp or DtmlDelp on a help
ile whose name does not contain the ull path to the ile! the help e,ecutable will
loo" on the ile system the (S was installed on in the QDelpR directory or the help
ile #e.g.! c2F+inATFhelp&. I the ile cannot be ound! +indows has two registry
"eys under
D67E-6%('A%6)A'DIAEFS(BT+A<EF)I'<(S(BTF+IA$(+S that the
e,ecutables use to ind the ile. (ne is or use by +inDelp and the "ey name is
QDelpR. DtmlDelp uses the other "ey and its name is QDtml DelpR. The help
e,ecutable used will loo" under the appropriate "ey or a string value whose name
is the help ilename and whose value is the path to the help ile. The path should
not contain the ilename! only the path. Dence i an addinOs registered help
ilename does not contain the ull path! and the help ile does not e,ist in the
+indows help directory! the addin should add a registry value under the
appropriate "ey.
Sample &e$istry )ile
RE7EDIT@
ACop3i)ht (C) ;000 Uni)aphics Sol+tions2 All i)hts eseved2
AChan)es /o RE7ISTR9 /o!at Chan)e
A ;BCDEC00 Fs"ielat
RE7EDIT@
A Sa!ple scipt /o $"1'ased AddIns2
A $" a+to!aticall3 p+ts o+t !ost o/ the 'asic e) enties2 F+st add the Solid
Ed)e speci/ic enties2
GH?E9&CLASSES&ROOT4CLSID4HCEC(IJE"1E(EB1;;DD1"EIE1BIBBKL"@DJBDMN
O<:M3 Solid Ed)e Add1in CLSID:
209
Chapter 24 Solid Edge Programmer's Guide
:A+toConnect:<d*od.BBBBBBB;
:@B0:<:This is !3 localiPed (US En)lish) addin e)ist3 stin):
GH?E9&CLASSES&ROOT4CLSID4HCEC(IJE"1E(EB1;;DD1"EIE1BIBBKL"@DJBDM4Envion!ent
Cate)oiesN
GH?E9&CLASSES&ROOT4CLSID4HCEC(IJE"1E(EB1;;DD1"EIE1BIBBKL"@DJBDM4Envion!ent
Cate)oies4HDLL;IK0L1B0DL1;;d;1"ABE1BIBBKLDKBLBDMN
O<:Solid Ed)e #at Envion!ent:
GH?E9&CLASSES&ROOT4CLSID4HCEC(IJE"1E(EB1;;DD1"EIE1BIBBKL"@DJBDM4I!ple!ented
Cate)oiesN
GH?E9&CLASSES&ROOT4CLSID4HCEC(IJE"1E(EB1;;DD1"EIE1BIBBKL"@DJBDM4I!ple!ented
Cate)oies4HDL";DDD;1D"BK1;;dD1"JI01BIBBKLEI"IBDMN
O<:M3 Solid Ed)e AddIn:
A Re)iste the SolidEd)e Addins CATID in case it is not alead3 e)isteed
GH?E9&CLASSES&ROOT4Co!ponent Cate)oies4HDL";DDD;1D"BK1;;dD1"JI01
BIBBKLEI"IBDMN
O<:Solid Ed)e AddIn CATID:
GH?E9&CLASSES&ROOT4Co!ponent Cate)oies4HDL";DDD;1D"BK1;;dD1"JI01
BIBBKLEI"IBDM4@B0N
O<:This is the CATID /o SolidEd)e AddIn:
210
Working with Add-ins Chapter 24
211