// ===========================================================================
// Copyright 2018 Autodesk, Inc. All rights reserved.
//
// Use of this software is subject to the terms of the Autodesk license
// agreement provided at the time of installation or download, or which
// otherwise accompanies this software in either electronic or hard copy form.
// ===========================================================================
//
//
//  Creation Date:  05 July 2006
//
//<doc>
//<name addPanelCategory>
//
//<synopsis>
//		int addPanelCategory( string $name, string $insertAfter, string $cmd )
//
//<description>
//		Add a new category to the Panels pulldown menus. The Panels
//	pulldowns are the menus specified per viewport which allow the user
//	to switch between different camera views, or different layouts, etc.
//	The new category is defined by a new button which cascades into a
//	separate user-definable pulldown menu.
//
//		For example, you've defined your own camera type called "Stereo"
//	and you want all your stereo cameras to appear under a separate 
//	category in the Panels pulldowns for convenience. What you can do from
//	the plug-in where you define your cameras of this type when the plug-in
//	first loads is to issue a MEL command of the form:
//<ol>
//			addPanelCategory( "Stereo", "Perspective", "buildStereoPulldown" );
//</ol>
//		The preceeding call adds a new button called "Stereo" to the Panels
//	pulldown menus, with the new button situated immediately after the existing
//	"Perspective" buttom. The Stereo button displays a cascade icon and when
//	selected, a user-implemented MEL procedure "buildStereoPulldown" is invoked
//	to allow the user to define the entries for the cascading menu. An example
//	for building a Perspective list might be:
//<p>
//	global proc buildPerspectivePulldown( string $parent, string $panel )<br>
//	{<br>
//		string $cameras[] = `listCameras -perspective`;<br>
//<br>
//		// Rebuild menu<br>
//		//<br>
//		setParent -m $parent;<br>
//		menu -e -deleteAllItems $parent;<br>
//<br>
//		for ($camera in $cameras) {<br>
//			menuItem -l $camera -command<br>
//				("lookThroughModelPanel "+$camera+" "+$panel);<br>
//		}<br>
//	}
//<p>
//		For a type of camera other than perspective, the user may want
//	to define some special means for identifying the camera type.
//<p>
//		This apparatus is not specific to cameras. It is a general mechanism
//	for adding a new cascading menu item to the Panels menu. For example,
//	it could list custom model panels as well.
//<p>
//		The user will most likely add the new category upon loading the
//	new data from their plug-in code. To determine if a given category
//	has already been added, the command listPanelCategories() is provided.
//	To remove a category, the removePanelCategory() command is provided.
//
//<flags>
//		string	 $name			The name of the category that appears on
//								the new cascading button when added. The
//								name specifies the label.
//		string	 $insertAfter	The menu item to insert immediately after. 
//								This is the label value for the button,
//								and examples are "Perspective", "Layouts",
//								etc. Since the Panels menu may not have
//								been built yet, the check that the $insertAfter
//								button exists is not performed until the menu
//								is posted.
//		string	 $cmd			A MEL command to be executed when the
//								new category button is depressed. typically
//								this will build an on-demand pulldown menu.
//
//<returns>
//		int : Returns false if the category is already defined, and true
//			  on success.
//
//<examples>
//  addPanelCategory( "Stereo", "Perspective", "buildStereoPulldown" );
//
//</doc>
//

global proc int addPanelCategory( string $name, string $insertAfter, string $cmd )
{
	global string $gCategoryName[];
	global string $gCategoryInsertAfter[];
	global string $gCategoryCmd[];

	// Issue an error and return if the category already exists.
	//
	int $count = stringArrayCount( $name, $gCategoryName );
	if ( $count > 0 ) {
		string $msg = (uiRes("m_addPanelCategory.kCategoryExists"));
		error `format -s $name $msg`;
		return( false );
	}

	// Add the category to the list.
	//
	int $nc = size( $gCategoryName );
	$gCategoryName[$nc] = $name;
	$gCategoryInsertAfter[$nc] = $insertAfter;
	$gCategoryCmd[$nc] = $cmd;

	return( true );
}