Making self documenting COM components

[Dominic Mitchell]

Dominic, TypeDefs? Is this the same as an Enum in the VB world? I have used Enums to establish a valid group
of values for a property in VB. So this isn't available in PowerBasic?

In the context of this discussion, yes.

For example, given the following BASIC code

' Tree item shape
%TIO_NOSHAPE     = &H00000000
%TIO_ELLIPSE     = &H00000001
%TIO_RECT        = &H00000002
%TIO_ROUNDRECT   = &H00000003
%TIO_CIRCLE      = &H00000004
%TIO_DIAMOND     = &H00000005
%TIO_TRIANGLE    = &H00000006
%TIO_SHADOWED    = &H00000800 

METHOD SetShape(BYVAL Shape AS LONG, BYVAL cxBorder AS LONG, BYVAL BorderColor AS LONG) AS LONG

  ' Code to change node attributes
  
END METHOD

A hand-built IDL file would look like this.
This sample does not do this, but each constant can also be documented.
Also, the IDL snippets just shows the enumeration and the method.

  typedef [uuid(BF0884DC-2A65-463E-86E1-174C0E6A85DA), v1_enum, helpstring("Tree control Node shape flags")]
  enum ShapeConstants {
    tscNoShape           = 0x00000000,
    tscEllipse           = 0x00000001,
    tscRect              = 0x00000002,
    tscRoundRect         = 0x00000003,
    tscCircle            = 0x00000004,
    tscDiamond           = 0x00000005,
    tscTriangle          = 0x00000006,
    tscShadowed          = 0x00000800
  } ShapeConstants;
  
  
    [id(0x00000016), helpstring("Returns/sets the shape of a Node object.")]
    HRESULT SetShape([in] ShapeConstants Shape, [in] long cxBorder, [in] OLE_COLOR BorderColor);

The PowerBASIC IDL file would look like this

    [id(0x00000016)]
    HRESULT SetShape([in] long Shape, [in] long cxBorder, [in] long BorderColor);

[Dominic Mitchell]

So what about those procedure attributes? Is there anything like that available in PowerBasic? They're also needed to make self documenting COM objects.

No. You will have to edit the *.tlb file. Actually, you will have to edit the *.idl file.
The *.tlb file is the binary file that is produced when an *.idl file is compiled.

[WesWesthaver]

Dominic, TypeDefs? Is this the same as an Enum in the VB world? I have used Enums to establish a valid group of values for a property in VB. So this isn't available in PowerBasic?

That's really too bad. They are a great tool for creating self documenting COM objects.

So what about those procedure attributes? Is there anything like that available in PowerBasic? They're also needed to make self documenting COM objects.

[Dominic Mitchell]

At present, self documenting COM components are not possible in PowerBASIC.
Another thing that is great for intellisense is typedefs. This allows an editor to display
a lists of constants for a parameter based on its typedef.

For example, when you type

me.ProjectorCommand(

in an editor, it would display a list of possible commands such as

PWR?
VOL?
LAMP?

for the parameter saving the programmer the trouble of having to look them up.

To do extensive documenting and typdefs, you will need to hand-tweak the type library file(*.tlb).

[José Roca]

They are very useful to obfuscate code

When you find a VB line of code like:

Flds("urn:schemas:mailheader:content-type") = "text/html"

If you are using another language, you have to look in the interface definitions in search for properties with an identifier of 0 to come with:

Flds.Item("urn:schemas:mailheader:content-type").Value = "text/plain"

[WesWesthaver]

Yeah, I found that info after I posted. But I haven't tried it yet. I always liked default properties but haven't they been determined to be "evil" by Microsoft now-a-days? At least in DotNet? Or am I imagining things again?

-Wes

[José Roca]

For default properties, assign to it a DispID of 0 ( <0> ).

[WesWesthaver]

Can anyone tell me where to find the functional equivalent of the VisualBasic 6.0 "Procedure Attributes" in PowerBasic? In VB6 you could place your cursor on a property or method and then select:

Tools | Procedure Attributes...

In this dialog you could configure the help text that would be displayed in the com browser for each method or property in your class. I used it extensively to make my components self documenting.

You could also define a particular property as the "Default Property" which was also very handy.

So, What's the PB way of doing these things?

-Wes