[Code] Layers Panel API

jiminy-billy-bob · 19 May 2014, 09:37

I've added an API to Layers Panel so that any plugin can interact with it.
This is useful if your plugin creates a bunch of layers that you want to group automatically. Or if you are developing a render engine and want to read if a layer is tagged as to be rendered. Etc.

Layers Panel assigns unique IDs to layers, which are persistent between sessions. This is NOT the layer's entityID.
These unique IDs are shared with layer groups, which means that a group cannot have the same ID as a layer.

None of these methods are wrapped in start/commit_operation, so don't forget to do so when calling them.

Exemple

groupID = JBB_LayersPanel.add_group("Foo")
layer = Sketchup.active_model.layers.add "Bar"
layerID = JBB_LayersPanel.get_layerID(layer)
JBB_LayersPanel.nest_into(layerID, groupID)
JBB_LayersPanel.set_render_behav(layer, false)

The above code will result in this:

Methods

JBB_LayersPanel.add_group - Since 1.1.1

This is used to create a new layer group.

Arguments:

name (optional) : The name of the group. If nothing is passed, a unique name will be created (Something like "Group 1").

Returns:

ID : The ID of the group.

JBB_LayersPanel.add_group("Foo")
#=> 2

JBB_LayersPanel.collapse_group - Since 1.2.1

This is used to collapse a group.

Arguments:

ID : The ID of the group
all_scenes (optional) : If the model has multiple scenes, true will affect all scenes, false will only affect the active scene. Defaults as false

Returns:

nil

JBB_LayersPanel.collapse_group(2)

JBB_LayersPanel.delete_group - Since 1.1.1

This is used to delete a group.

Arguments:

ID : The ID of the group

Returns:

true if successful, false if unsuccessful.

JBB_LayersPanel.delete_group(2)
#=> true

JBB_LayersPanel.expand_group - Since 1.2.1

This is used to expand a group.

Arguments:

ID : The ID of the group
all_scenes (optional) : If the model has multiple scenes, true will affect all scenes, false will only affect the active scene. Defaults as false

Returns:

nil

JBB_LayersPanel.expand_group(2)

JBB_LayersPanel.get_groupID_by_name - Since 1.1.1

This is used to get the ID of a group from its name. Keep in mind that unlike layers, multiple groups can have the same name. In that case, an array with all the IDs is returned. This will change in 1.2.1 and always return an array.

Arguments:

name : The name of the group(s).

Returns:

ID : The ID(s) of the group(s). Integer if only one group is found, array if multiple groups are found. This will change in 1.2.1 and always return an array.

JBB_LayersPanel.get_groupID_by_name("Foo")
#=> 2

JBB_LayersPanel.get_group_name_by_ID - Since 1.1.1

This is used to get the name of a group from its ID.

Arguments:

ID : The ID of the group.

Returns:

name : The name of the group.

JBB_LayersPanel.get_group_name_by_ID(2)
#=> "Foo"

JBB_LayersPanel.get_layerID - Since 1.1.1

This is used to get the ID of a layer.

Arguments:

layer : A Layer object .

Returns:

ID : The ID of the layer.

layer = Sketchup.active_model.layers.add "Bar"
JBB_LayersPanel.get_layerID(layer)
#=> 3

JBB_LayersPanel.get_layer_by_ID - Since 1.1.1

This is used to get the Layer object from its ID.

Arguments:

ID : The ID of the layer.

Returns:

layer : A Layer object .

JBB_LayersPanel.get_layer_by_ID(3)
#=> #<Sketchup;;Layer;0xa995210>

JBB_LayersPanel.is_active? - Since 1.1.1

This is used to check if Layers Panel is installed and loaded. Of course, if Layers Panel is not installed, this will raise an error.

Returns:

true

begin
	JBB_LayersPanel.is_active?
	lp_active = true
rescue
	lp_active = false
end

JBB_LayersPanel.move_after - Since 1.2.0

This is used to sort an item (layer or group) after another item.

Arguments:

itemID : The ID of the item.
targetID : The ID of the target item.

Returns:

true if successful, false if unsuccessful.

JBB_LayersPanel.move_after(2, 3)
#=> true

JBB_LayersPanel.move_before - Since 1.2.0

This is used to sort an item (layer or group) before another item.

Arguments:

itemID : The ID of the item.
targetID : The ID of the target item.

Returns:

true if successful, false if unsuccessful.

JBB_LayersPanel.move_before(3, 2)
#=> true

JBB_LayersPanel.nest_into - Since 1.2.1

This is used to nest an item (layer or group) inside another group.

Arguments:

itemID : The ID of the item.
targetID : The ID of the target group.

Returns:

true if successful, false if unsuccessful.

JBB_LayersPanel.nest_into(3, 2)
#=> true

JBB_LayersPanel.rename_group - Since 1.1.1

This is used to rename a group. This will always return true, no matter if the group exists or not.

Arguments:

ID : The ID of the group.
name : The new name of the group.

Returns:

true

JBB_LayersPanel.rename_group(2, "Foobar")
#=> true

JBB_LayersPanel.render? - Since 1.0.5

This is used to get a layer's render behaviour (if it's tagged as "to be rendered" or not). This is the "teapot" in Layers Panel's dialog.

Arguments:

layer : A Layer object .

Returns:

true if tagged as "to be rendered", false if not.

layer = Sketchup.active_model.layers.add "Bar"
JBB_LayersPanel.render?(layer)
#=> true

JBB_LayersPanel.set_render_behav - Since 1.1.1

This is used to set a layer's render behaviour (tagged as "to be rendered" or not). This is the "teapot" in Layers Panel's dialog.

Arguments:

layer : A Layer object .
render : The render behaviour (true or false)

Returns:

nil

[code:3tah975b]layer = Sketchup.active_model.layers.add "Bar"
JBB_LayersPanel.set_render_behav(layer, false)
JBB_LayersPanel.render?(layer)
#=> false[/code:3tah975b]

JBB_LayersPanel.version - Since 1.1.1

This is used to get the installed version of Layers Panel.

Returns:

version : The decimal form of the version

[code:3tah975b]JBB_LayersPanel.version
#=> 1.1.1[/code:3tah975b]

jiminy-billy-bob · 19 May 2014, 09:38

Let me know what you think. If you need other methods, etc...
I'd love to get feedback on this

Aerilius · 19 May 2014, 09:52

That looks good!
Just to be clear, get_groupID_by_name returns always an array (of one or more ids)?

I would have named sort_before/sort_after as insert_before/insert_after. Sorting reminds me of many cards .

jiminy-billy-bob · 19 May 2014, 10:01

@aerilius said:

Just to be clear, get_groupID_by_name returns always an array (of one or more ids)?

No, it returns ar array ONLY when there are multiple IDs. If there is just one, it's an integer.
Do you think it should always be an array?

@aerilius said:

I would have named sort_before/sort_after as insert_before/insert_after. Sorting reminds me of many cards .

The items are already present in the hierachy, it's just a way to move them around. So they're not "inserted".
I used "sort" because I use jQuery Sortable. But english is not my native language, so I'm not really familiar with these words.
Maybe simply "move" would do it?

Aerilius · 19 May 2014, 11:02

@jiminy-billy-bob said:

No, it returns ar array ONLY when there are multiple IDs. If there is just one, it's an integer.

But we cannot predict if there are several layers with same name. So we would need to write in our code – in any case – a type switch, or we will get somewhen a type error.
I try to design methods and algorithms so that they return always the same type (as if ruby was a type-safe language). Although maybe nil as alternative return value type is still ok in ruby.

jiminy-billy-bob · 19 May 2014, 12:14

Ok then, I'll change it in the next version.

Dan Rathbun · 19 May 2014, 18:07

Is JBB_LayersPanel a class or a module ?

jiminy-billy-bob · 19 May 2014, 20:34

A module.
Why?

Dan Rathbun · 20 May 2014, 15:20

@jiminy-billy-bob said:

A module.
Why?

Just checking. Keepin' ya honest.

(Only Ruby, and in rare instances the API or library gems, should define classes at the toplevel.)