element <defineLocation>
Namespace:
Type:
embedded complexType
Content:
complex, 11 attributes, 4 elements
Defined:
globally within component.xsd, see XML source
Used:
XML Representation Summary
<defineLocation
   
baseLocation
 = 
xsd:string
   
dir
 = 
xsd:string
   
domain
 = 
xsd:string
   
file
 = 
xsd:string
   
filter
 = 
xsd:string : "default"
   
id
 = 
xsd:string
   
ifEvents
 = 
list of xsd:string
   
isEventHandler
 = 
xsd:string
   
location
 = 
xsd:string
   
owned
 = 
xsd:string : "true"
   
realize
 = 
xsd:string : "false"
   
>
   
Content: 
</defineLocation>
May contain elements (4):
May be included in elements (3):
Known Usage Locations
Annotation
This element defines a location in source, such as a function in the main
file or a region of text in a class declaration.
This is a slight misnomer as this element does not by its presence realize
the location. Only when a contribution references
location id (or post 1.1: when realize="true" is used)
will the location be added to source.
XML Source
<xsd:element name="defineLocation">
<xsd:annotation>
<xsd:documentation>
This element defines a location in source, such as a function in the main
file or a region of text in a class declaration.
This is a slight misnomer as this element does not by its presence realize
the location. Only when a contribution references
location id (or post 1.1: when realize="true" is used)
will the location be added to source.
</xsd:documentation>
</xsd:annotation>
<xsd:complexType>
<xsd:sequence>
<xsd:choice maxOccurs="unbounded" minOccurs="0">
<xsd:element ref="template"/>
<xsd:element ref="inline"/>
<xsd:element ref="script"/>
<xsd:element ref="expandMacro"/>
</xsd:choice>
</xsd:sequence>
<xsd:attribute name="baseLocation" type="xsd:string" use="optional">
<xsd:annotation>
<xsd:documentation>
If defined, the location id this location lives inside. (E.g. a class inside a file,
an enum declaration inside a class, etc.)
</xsd:documentation>
</xsd:annotation>
</xsd:attribute>
<xsd:attribute name="domain" type="xsd:string" use="optional">
<xsd:annotation>
<xsd:documentation>
The source domain which controls how locations are interpreted and instantiated.
Only "cpp" is supported currently.
</xsd:documentation>
</xsd:annotation>
</xsd:attribute>
<xsd:attribute name="id" type="xsd:string" use="required">
<xsd:annotation>
<xsd:documentation>
The location identifier. This must be unique in a component. A derived component
may redefine a location.
</xsd:documentation>
</xsd:annotation>
</xsd:attribute>
<xsd:attribute name="dir" type="xsd:string" use="optional">
<xsd:annotation>
<xsd:documentation>
For a top-level location, where baseLocation is null, this is a
template-expanded reference to the project-relative directory to
use. Predefined variables ${src}, ${inc}, ${resource}, ${build}
are provided.
</xsd:documentation>
</xsd:annotation>
</xsd:attribute>
<xsd:attribute name="file" type="xsd:string" use="optional">
<xsd:annotation>
<xsd:documentation>
For a top-level location, where baseLocation is null, this is a
template-expanded filename relative to the directory specified by "dir".
</xsd:documentation>
</xsd:annotation>
</xsd:attribute>
<xsd:attribute name="location" type="xsd:string" use="required">
<xsd:annotation>
<xsd:documentation>
This describes the location relative to its base (use "" for a
top-level file location).

A location segment in the cpp domain is a string
representing a node in a C/C++ parse tree.  Each takes the syntax “<name>
‘(‘ <arguments…> ‘)’�?.  Certain nodes may only appear within certain
others.  This list defines top-level nodes:

class(<name>):
reference the class declaration for the class ‘name’, which may include namespaces (e.g.
“class(MyClass)�? or “class(${className})�?)

function(<name>(<arguments…)):
reference a function with the given signature.  ‘name’ may include namespaces
or represent a destructor.  ‘arguments’ is a comma-separated list of types. 
This list of arguments is currently not parsed and only the number of
arguments matters.  The arguments list may end in ellipsis (“…�?) to indicate
that any zero or more arguments are matched.  Again, the <template>
inside a <defineLocation> really defines the function.  (E.g.
“function(main(int,char**))�? or “function(${className}::method(void*)�?.)

region(<name>):
a region defines a commented block of text with no other syntactical clues.  The
block comments and the name are used to identify the block.  Thus, names should
be unique across a component.  (E.g. “region(Generated Includes)�?.)

enum(<name>):
a enum declaration with the given name.  Name must be non-empty (locations are
used to look up source, so anonymous enums cannot be unambiguously
identified).  (E.g. “enum(T${className}Ids)�?.)

namespace(<name>):
a namespace declaration with the given name, which may contain colons.  (E.g.
“namespace(std::tr1)�?)

to-file():
resolve to the current file of a location, i.e. get back to the root location.

Inside a class(), namespace() is not allowed, and this
additional segment is allowed:

bases():
references the base-class-list within a class declaration.  If the class’ defining text
already includes a base, then the defining text for the bases() location may be
omitted.  If a class’ defining text does not include a base, the bases()
location must include the leading colon in its defining text.  Otherwise,
contributions are individual class references with leading commas.

In a function(), only class(), region(), enum(), and to-file() are allowed.

In an enum(), bases() or region(), only region() and to-file() are allowed.
</xsd:documentation>
</xsd:annotation>
</xsd:attribute>
<xsd:attribute default="true" name="owned" type="xsd:string" use="optional">
<xsd:annotation>
<xsd:documentation>
Note: a string for macro use only; must resolve to "true" or "false".
If true, the location is marked generated in source and will be
regenerated from scratch on every save. Otherwise, the location
is generated only when missing.
</xsd:documentation>
</xsd:annotation>
</xsd:attribute>
<xsd:attribute default="default" name="filter" type="xsd:string" use="optional">
<xsd:annotation>
<xsd:documentation>
Defines a filter on contributions added to the location.
Available filters:
* unique-includes (can be applied anywhere, but scans files)
* unique-prototypes (can be applied in "class()" or children, but scans the class)
* unique-bases (can be applied to "bases()" or children, but scans the base class list)
</xsd:documentation>
</xsd:annotation>
</xsd:attribute>
<xsd:attribute name="isEventHandler" type="xsd:string" use="optional">
<xsd:annotation>
<xsd:documentation>
Note: a string for macro use only; must resolve to "true" or "false".
When "ifEvents" is non-empty, this flag tells the designer which particular
function is the user-editable event handler. So this usually is applied
to a function() location.
</xsd:documentation>
</xsd:annotation>
</xsd:attribute>
<xsd:attribute default="false" name="realize" type="xsd:string" use="optional">
<xsd:annotation>
<xsd:documentation>
Added post 1.1.
Note: a string for macro use only; must resolve to "true" or "false".
If true, a template for this location is automatically added when this location is defined.
Otherwise, the location is a placeholder and is not "realized" in actual source unless a template references it.
</xsd:documentation>
</xsd:annotation>
</xsd:attribute>
<xsd:attribute name="ifEvents" type="listOfStrings" use="optional">
<xsd:annotation>
<xsd:documentation>
If defined, a list of events, any of which must be bound for the
location to be declared. Otherwise, its id is not available and
the location is undefined.
</xsd:documentation>
</xsd:annotation>
</xsd:attribute>
</xsd:complexType>
</xsd:element>
Attribute Detail
baseLocation
If defined, the location id this location lives inside. (E.g. a class inside a file,
an enum declaration inside a class, etc.)
Type:
xsd:string
Use:
optional
Defined:
locally, within this element
XML Source
<xsd:attribute name="baseLocation" type="xsd:string" use="optional">
<xsd:annotation>
<xsd:documentation>
If defined, the location id this location lives inside. (E.g. a class inside a file,
an enum declaration inside a class, etc.)
</xsd:documentation>
</xsd:annotation>
</xsd:attribute>

dir
For a top-level location, where baseLocation is null, this is a
template-expanded reference to the project-relative directory to
use. Predefined variables ${src}, ${inc}, ${resource}, ${build}
are provided.
Type:
xsd:string
Use:
optional
Defined:
locally, within this element
XML Source
<xsd:attribute name="dir" type="xsd:string" use="optional">
<xsd:annotation>
<xsd:documentation>
For a top-level location, where baseLocation is null, this is a
template-expanded reference to the project-relative directory to
use. Predefined variables ${src}, ${inc}, ${resource}, ${build}
are provided.
</xsd:documentation>
</xsd:annotation>
</xsd:attribute>

domain
The source domain which controls how locations are interpreted and instantiated.
Only "cpp" is supported currently.
Type:
xsd:string
Use:
optional
Defined:
locally, within this element
XML Source
<xsd:attribute name="domain" type="xsd:string" use="optional">
<xsd:annotation>
<xsd:documentation>
The source domain which controls how locations are interpreted and instantiated.
Only "cpp" is supported currently.
</xsd:documentation>
</xsd:annotation>
</xsd:attribute>

file
For a top-level location, where baseLocation is null, this is a
template-expanded filename relative to the directory specified by "dir".
Type:
xsd:string
Use:
optional
Defined:
locally, within this element
XML Source
<xsd:attribute name="file" type="xsd:string" use="optional">
<xsd:annotation>
<xsd:documentation>
For a top-level location, where baseLocation is null, this is a
template-expanded filename relative to the directory specified by "dir".
</xsd:documentation>
</xsd:annotation>
</xsd:attribute>

filter
Defines a filter on contributions added to the location.
Available filters:
* unique-includes (can be applied anywhere, but scans files)
* unique-prototypes (can be applied in "class()" or children, but scans the class)
* unique-bases (can be applied to "bases()" or children, but scans the base class list)
Type:
xsd:string
Use:
optional
Default:
"default"
Defined:
locally, within this element
XML Source
<xsd:attribute default="default" name="filter" type="xsd:string" use="optional">
<xsd:annotation>
<xsd:documentation>
Defines a filter on contributions added to the location.
Available filters:
* unique-includes (can be applied anywhere, but scans files)
* unique-prototypes (can be applied in "class()" or children, but scans the class)
* unique-bases (can be applied to "bases()" or children, but scans the base class list)
</xsd:documentation>
</xsd:annotation>
</xsd:attribute>

id
The location identifier. This must be unique in a component. A derived component
may redefine a location.
Type:
xsd:string
Use:
required
Defined:
locally, within this element
XML Source
<xsd:attribute name="id" type="xsd:string" use="required">
<xsd:annotation>
<xsd:documentation>
The location identifier. This must be unique in a component. A derived component
may redefine a location.
</xsd:documentation>
</xsd:annotation>
</xsd:attribute>

ifEvents
If defined, a list of events, any of which must be bound for the
location to be declared. Otherwise, its id is not available and
the location is undefined.
Type:
Use:
optional
Defined:
locally, within this element
XML Source
<xsd:attribute name="ifEvents" type="listOfStrings" use="optional">
<xsd:annotation>
<xsd:documentation>
If defined, a list of events, any of which must be bound for the
location to be declared. Otherwise, its id is not available and
the location is undefined.
</xsd:documentation>
</xsd:annotation>
</xsd:attribute>

isEventHandler
Note: a string for macro use only; must resolve to "true" or "false".
When "ifEvents" is non-empty, this flag tells the designer which particular
function is the user-editable event handler. So this usually is applied
to a function() location.
Type:
xsd:string
Use:
optional
Defined:
locally, within this element
XML Source
<xsd:attribute name="isEventHandler" type="xsd:string" use="optional">
<xsd:annotation>
<xsd:documentation>
Note: a string for macro use only; must resolve to "true" or "false".
When "ifEvents" is non-empty, this flag tells the designer which particular
function is the user-editable event handler. So this usually is applied
to a function() location.
</xsd:documentation>
</xsd:annotation>
</xsd:attribute>

location
This describes the location relative to its base (use "" for a
top-level file location).

A location segment in the cpp domain is a string
representing a node in a C/C++ parse tree.  Each takes the syntax “<name>
‘(‘ <arguments…> ‘)’�?.  Certain nodes may only appear within certain
others.  This list defines top-level nodes:

class(<name>):
reference the class declaration for the class ‘name’, which may include namespaces (e.g.
“class(MyClass)�? or “class(${className})�?)

function(<name>(<arguments…)):
reference a function with the given signature.  ‘name’ may include namespaces
or represent a destructor.  ‘arguments’ is a comma-separated list of types. 
This list of arguments is currently not parsed and only the number of
arguments matters.  The arguments list may end in ellipsis (“…�?) to indicate
that any zero or more arguments are matched.  Again, the <template>
inside a <defineLocation> really defines the function.  (E.g.
“function(main(int,char**))�? or “function(${className}::method(void*)�?.)

region(<name>):
a region defines a commented block of text with no other syntactical clues.  The
block comments and the name are used to identify the block.  Thus, names should
be unique across a component.  (E.g. “region(Generated Includes)�?.)

enum(<name>):
a enum declaration with the given name.  Name must be non-empty (locations are
used to look up source, so anonymous enums cannot be unambiguously
identified).  (E.g. “enum(T${className}Ids)�?.)

namespace(<name>):
a namespace declaration with the given name, which may contain colons.  (E.g.
“namespace(std::tr1)�?)

to-file():
resolve to the current file of a location, i.e. get back to the root location.

Inside a class(), namespace() is not allowed, and this
additional segment is allowed:

bases():
references the base-class-list within a class declaration.  If the class’ defining text
already includes a base, then the defining text for the bases() location may be
omitted.  If a class’ defining text does not include a base, the bases()
location must include the leading colon in its defining text.  Otherwise,
contributions are individual class references with leading commas.

In a function(), only class(), region(), enum(), and to-file() are allowed.

In an enum(), bases() or region(), only region() and to-file() are allowed.
Type:
xsd:string
Use:
required
Defined:
locally, within this element
XML Source
<xsd:attribute name="location" type="xsd:string" use="required">
<xsd:annotation>
<xsd:documentation>
This describes the location relative to its base (use "" for a
top-level file location).

A location segment in the cpp domain is a string
representing a node in a C/C++ parse tree.  Each takes the syntax “<name>
‘(‘ <arguments…> ‘)’�?.  Certain nodes may only appear within certain
others.  This list defines top-level nodes:

class(<name>):
reference the class declaration for the class ‘name’, which may include namespaces (e.g.
“class(MyClass)�? or “class(${className})�?)

function(<name>(<arguments…)):
reference a function with the given signature.  ‘name’ may include namespaces
or represent a destructor.  ‘arguments’ is a comma-separated list of types. 
This list of arguments is currently not parsed and only the number of
arguments matters.  The arguments list may end in ellipsis (“…�?) to indicate
that any zero or more arguments are matched.  Again, the <template>
inside a <defineLocation> really defines the function.  (E.g.
“function(main(int,char**))�? or “function(${className}::method(void*)�?.)

region(<name>):
a region defines a commented block of text with no other syntactical clues.  The
block comments and the name are used to identify the block.  Thus, names should
be unique across a component.  (E.g. “region(Generated Includes)�?.)

enum(<name>):
a enum declaration with the given name.  Name must be non-empty (locations are
used to look up source, so anonymous enums cannot be unambiguously
identified).  (E.g. “enum(T${className}Ids)�?.)

namespace(<name>):
a namespace declaration with the given name, which may contain colons.  (E.g.
“namespace(std::tr1)�?)

to-file():
resolve to the current file of a location, i.e. get back to the root location.

Inside a class(), namespace() is not allowed, and this
additional segment is allowed:

bases():
references the base-class-list within a class declaration.  If the class’ defining text
already includes a base, then the defining text for the bases() location may be
omitted.  If a class’ defining text does not include a base, the bases()
location must include the leading colon in its defining text.  Otherwise,
contributions are individual class references with leading commas.

In a function(), only class(), region(), enum(), and to-file() are allowed.

In an enum(), bases() or region(), only region() and to-file() are allowed.
</xsd:documentation>
</xsd:annotation>
</xsd:attribute>

owned
Note: a string for macro use only; must resolve to "true" or "false".
If true, the location is marked generated in source and will be
regenerated from scratch on every save. Otherwise, the location
is generated only when missing.
Type:
xsd:string
Use:
optional
Default:
"true"
Defined:
locally, within this element
XML Source
<xsd:attribute default="true" name="owned" type="xsd:string" use="optional">
<xsd:annotation>
<xsd:documentation>
Note: a string for macro use only; must resolve to "true" or "false".
If true, the location is marked generated in source and will be
regenerated from scratch on every save. Otherwise, the location
is generated only when missing.
</xsd:documentation>
</xsd:annotation>
</xsd:attribute>

realize
Added post 1.1.
Note: a string for macro use only; must resolve to "true" or "false".
If true, a template for this location is automatically added when this location is defined.
Otherwise, the location is a placeholder and is not "realized" in actual source unless a template references it.
Type:
xsd:string
Use:
optional
Default:
"false"
Defined:
locally, within this element
XML Source
<xsd:attribute default="false" name="realize" type="xsd:string" use="optional">
<xsd:annotation>
<xsd:documentation>
Added post 1.1.
Note: a string for macro use only; must resolve to "true" or "false".
If true, a template for this location is automatically added when this location is defined.
Otherwise, the location is a placeholder and is not "realized" in actual source unless a template references it.
</xsd:documentation>
</xsd:annotation>
</xsd:attribute>
Content Element Detail
expandMacro
Type:
embedded (extension of ConditionalSourceGen), complex content
Defined:
by reference, within this element
XML Source
<xsd:element ref="expandMacro"/>

inline
Type:
embedded (extension of ConditionalSourceGenString), simple content
Defined:
by reference, within this element
XML Source
<xsd:element ref="inline"/>

script
Type:
embedded, empty content
Defined:
by reference, within this element
XML Source
<xsd:element ref="script"/>

template
Type:
embedded (extension of ConditionalSourceGenString), empty content
Defined:
by reference, within this element
XML Source
<xsd:element ref="template"/>