API: AIUser.h Source File

00001 #ifndef __AIUser__
00002 #define __AIUser__
00003 
00004 /*
00005  *        Name: AIUser.h
00006  *   $Revision: 15 $
00007  *      Author:
00008  *        Date:
00009  *     Purpose: Adobe Illustrator User Utilities Suite.
00010  *
00011  * ADOBE INCORPORATED
00012  * Copyright 2019 Adobe Systems Incorporated.
00013  * All rights reserved.
00014  *
00015  * NOTICE:  Adobe permits you to use, modify, and distribute this file
00016  * in accordance with the terms of the Adobe license agreement
00017  * accompanying it. If you have received this file from a source other
00018  * than Adobe, then your use, modification, or distribution of it
00019  * requires the prior written permission of Adobe.
00020  *
00021  */
00022 
00023 
00024 /*******************************************************************************
00025  **
00026  **     Imports
00027  **
00028  **/
00029 
00030 #ifndef __AIArt__
00031 #include "AIArt.h"
00032 #endif
00033 
00034 #ifndef __AITypes__
00035 #include "AITypes.h"
00036 #endif
00037 
00038 #ifndef __AIColor__
00039 #include "AIColor.h"
00040 #endif
00041 
00042 #ifndef __AIMenu__
00043 #include "AIMenu.h"
00044 #endif
00045 
00046 #ifndef __AIFileFormat__
00047 #include "AIFileFormat.h"
00048 #endif
00049 
00050 #ifndef __AIDocumentView__
00051 #include "AIDocumentView.h"
00052 #endif
00053 
00054 #include "IAIFilePath.hpp"
00055 #include "IAILocale.h"
00056 
00057 #include "AIHeaderBegin.h"
00058 
00062 /************************************************************************s*******
00063  **
00064  **     Constants
00065  **
00066  **/
00067 
00068 #define kAIUserSuite                            "AI User Suite"
00069 #define kAIUserSuiteVersion18           AIAPI_VERSION(18)
00070 #define kAIUserSuiteVersion                     kAIUserSuiteVersion18
00071 #define kAIUserVersion                          kAIUserSuiteVersion
00072 
00073 #if Macintosh || MSWindows
00074 #define kAIMacUserSuite                         "AI Mac User Suite"
00075 #define kAIMacUserSuiteVersion8         AIAPI_VERSION(8)
00076 #define kAIMacUserSuiteVersion          kAIMacUserSuiteVersion8
00077 #define kAIMacUserVersion                       kAIMacUserSuiteVersion
00078 #endif
00079 
00081 enum {
00083         kShortUnits,
00085         kLongSingularUnits,
00087         kLongPluralUnits
00088 };
00089 
00094 enum AIAnswer {
00095         kAIAnswer_No = 0,
00096         kAIAnswer_Yes,
00097         kAIAnswer_Cancel,
00098         kAIAnswer_Invalid =  0xFFFFFFFF
00099 };
00100 
00106 enum AIValidationStage
00107 {
00109         kAIValidationStage_interactive = 0,
00111         kAIValidationStage_onOk = 1
00112 };
00113 
00118 enum AIPredefinedCursor
00119 {
00120         kAIIBeamCursorID = -1,
00121         kAICrossCursorID = -2,
00122         kAIWaitCursorID = -3,
00123         kAIArrowCursorID = -4
00124 };
00125 
00128 #define kUnknownUnitsErr                '?UNT'
00129 
00132 #define kApplicationNotFoundErr 'App?'
00133 
00136 #define kObjectNotLinkedErr             '!Lnk'
00137 
00138 
00140 typedef ai::uint32 AIUserDateTime;
00141 
00143 typedef struct _t_Opaque_AIResourceManagerHandle *AIResourceManagerHandle;
00144 
00152 typedef AIBoolean (*IsValidInputProc) (AIValidationStage validationStage, const ai::UnicodeString &input, ai::UnicodeString &errorStr, void *userdata);
00153 
00163 typedef AIBoolean (*UpdateProgressProc) (ai::int32 current, ai::int32 max);
00164 
00166 #define kAIUniversalLocaleFormat                0x0000
00167 
00168 #define kAIResourceLocaleFormat                 0x0001
00169 
00170 #define kAISystemLocaleFormat                   0x0002
00171 
00174 #define kAIShortDateFormat                              0x0000
00175 
00177 #define kAILongDateFormat                               0x0100
00178 
00181 #define kAIAbbrevDateFormat                             0x0200
00182 
00184 #define kAIShortTimeFormat                              0x0000
00185 
00187 #define kAILongTimeFormat                               0x0100
00188 
00189 
00190 /*******************************************************************************
00191  **
00192  **     Types
00193  **
00194  **/
00195 
00250 struct AIAutoNameGenerator
00251 {
00252 
00255         ai::int32 maximumLength;
00256 
00258         AIBoolean uniqueNames;
00259 
00261     ai::UnicodeString baseName;
00262 
00265         ai::int32 nextNewNameIndex;
00266 
00277     AIAPI AIErr (*HasName) (AIAutoNameGenerator &self, const ai::UnicodeString &name, AIBoolean &hasit);
00278 };
00279 
00280 
00281 
00282 
00286 struct AIFileDialogFilters
00287 {
00292         void AddFilter(const ai::UnicodeString &desc);
00293 
00294 
00302         void AddFilter(const ai::UnicodeString &desc, const ai::UnicodeString &pattern);
00303 
00310         const ai::UnicodeString &GetFilter() const;
00311 
00312 private:
00313         ai::UnicodeString filterStr;
00314 };
00315 
00319 struct AIExpressionOptions
00320 {
00325         ai::uint32 unit;
00326 
00328         AIDouble minValue;
00329 
00331         AIDouble maxValue;
00332 
00335         AIDouble oldValue;
00336 
00338         ai::uint32 precision;
00339 
00340 };
00341 
00349 struct AIUserSuite {
00350 
00357         AIAPI AIBoolean (*Cancel) ( void );
00358 
00365         AIAPI void (*UpdateProgress) ( ai::int32 current, ai::int32 max );
00366 
00374         AIAPI void(*SetUpdateProgressCallback) (UpdateProgressProc func);
00375 
00381         AIAPI void (*SetProgressText) ( const ai::UnicodeString& text );
00382 
00386         AIAPI void (*CloseProgress) ( void );
00387 
00397     AIAPI void (*AIRealToString) ( AIReal value, ai::int16 precision, ai::UnicodeString& string );
00398 
00406         AIAPI void (*StringToAIReal) ( const ai::UnicodeString& string, AIReal *value );
00416     AIAPI void (*IUAIRealToString) ( AIReal value, ai::int16 precision, ai::UnicodeString& string );
00417     
00428     AIAPI void (*IUAIRealToStringWithLocale) ( AIReal value, ai::int16 precision, ai::UnicodeString& string, const ai::LocaleID locale );
00429     
00440     AIAPI void (*IUAIRealToStringWithLocaleWithoutScale) ( AIReal value, ai::int16 precision, ai::UnicodeString& string, const ai::LocaleID locale );
00441 
00449         AIAPI void (*IUStringToAIReal) ( const ai::UnicodeString& string, AIReal *value );
00450 
00463         AIAPI AIErr (*IUAIRealToStringUnits) ( AIReal value, ai::int32 precision, ai::UnicodeString& string );
00464     
00477     AIAPI AIErr (*IUAIRealToStringUnitsWithoutScale) ( AIReal value, ai::int32 precision, ai::UnicodeString& string );
00478 
00490         AIAPI void (*IUStringUnitsToAIReal) ( const ai::UnicodeString& string, AIReal *value );
00491     
00503     AIAPI void (*IUStringUnitsToAIRealWithoutScale) ( const ai::UnicodeString& string, AIReal *value );
00504 
00514     AIAPI AIErr (*GetUnitsString) ( ai::int16 format, ai::UnicodeString& string );
00515 
00522         AIAPI AIErr (*GetGlobalObjectDisplayName)( ai::UnicodeString& name );
00523 
00530         AIAPI AIErr (*EditInOriginalApp) ( AIArtHandle art );
00531 
00534         AIAPI AIErr (*AppIdle) ( void );
00535 
00540         AIAPI AIErr (*BuildDirectoryMenu) ( AIPlatformMenuHandle menu, const ai::FilePath &fileSpec);
00541 
00546         AIAPI AIErr (*GetIndexedDirectorySpec) ( ai::FilePath &fileSpec, ai::int32 index);
00547 
00551         AIAPI AIErr (*RevealTheFile) ( const ai::FilePath &fileSpec);
00552 
00556         AIAPI void (*DisableProgressCancel) ( void );
00557 
00566         AIAPI AIBoolean (*OKToAllocateMemory) ( void );
00567 
00568         // Introduced in AI 11
00572         AIAPI AIErr (*GetDateAndTime)(AIUserDateTime *outValue);
00573 
00574         /* Formats a date into a Unicode string.
00575                         @param inValue The date to format, or \c NULL to format the current date-time value.
00576                         @param formatFlag The format to use, one of:
00577                                 <br> \c #kAIShortDateFormat
00578                                 <br> \c #kAILongDateFormat
00579                                 <br> \c #kAIAbbrevDateFormat
00580                         @param dateStringUS [out] A buffer in which to return the formatted date string.
00581                 */
00582         AIAPI AIErr (*GetDateString)(const AIUserDateTime *inValue, const ai::int32 formatFlag, ai::UnicodeString& dateStringUS);
00583 
00584         /* Formats a time into a Unicode string.
00585                         @param inValue The time to format, or \c NULL to format the current date-time value.
00586                         @param formatFlag The format to use, one of:
00587                                 <br> \c #kAIShortTimeFormat
00588                                 <br> \c #kAILongTimeFormat
00589                         @param dateStringUS [out] A buffer in which to return the formatted time string.
00590                 */
00591         AIAPI AIErr (*GetTimeString)(const AIUserDateTime *inValue, const ai::int32 formatFlag, ai::UnicodeString& dateStringUS);
00592 
00597         AIAPI AIErr (*GetYear)(const AIUserDateTime *inValue, int *year);
00598 
00603         AIAPI AIErr (*GetMonth)(const AIUserDateTime *inValue, int *month);
00604 
00609         AIAPI AIErr (*GetDay)(const AIUserDateTime *inValue, int *day);
00610 
00615         AIAPI AIErr (*GetHour)(const AIUserDateTime *inValue, int *hour);
00616 
00621         AIAPI AIErr (*GetMinute)(const AIUserDateTime *inValue, int *minute);
00622 
00627         AIAPI AIErr (*GetSecond)(const AIUserDateTime *inValue, int *second);
00628 
00633         AIAPI AIErr (*GetDayOfWeek)(const AIUserDateTime *inValue, int *dayOfWeek);
00634 
00639         AIAPI AIErr (*LaunchApp)(const ai::FilePath &spFileSpec, ASBoolean openDoc);
00640 
00647         AIAPI AIErr (*NextName) (AIAutoNameGenerator &set, ai::UnicodeString &name);
00648 
00656     AIAPI AIErr (*CopyOfName) (AIAutoNameGenerator &set, const ai::UnicodeString &original, ai::UnicodeString &copy);
00657 
00667         AIAPI AIErr (*SameName) (const ai::UnicodeString &name1, const ai::UnicodeString &name2, AIBoolean &same);
00668 
00669 
00677         AIAPI AIErr (*PutFileDialog)(const ai::UnicodeString &title, const AIFileDialogFilters*, const ai::UnicodeString &defaultName, ai::FilePath &ioFilePath);
00678 
00685         AIAPI AIErr (*GetFileDialog)(const ai::UnicodeString &title, const AIFileDialogFilters*, ai::FilePath &ioFilePath);
00686 
00692         AIAPI AIErr (*GetDirectoryDialog)(const ai::UnicodeString &title, ai::FilePath &ioFilePath);
00693 
00703         AIAPI AIBoolean (*OKCancelAlert) (const ai::UnicodeString& msg, AIBoolean defaultOk, const char* dontShowKey);
00704 
00712         AIAPI void (*WarningAlert) (const ai::UnicodeString& msg, const char* dontShowKey);
00713 
00721         AIAPI void (*MessageAlertEx) (const ai::UnicodeString& msg, const char* dontShowKey);
00722 
00731         AIAPI AIAnswer (*QuestionAlert)(const ai::UnicodeString &msg);
00732 
00741         AIAPI AIAnswer (*YesNoAlert)(const ai::UnicodeString &msg);
00742 
00750         AIAPI void (*ErrorAlert)(const ai::UnicodeString &msg);
00751 
00759         AIAPI void (*MessageAlert)(const ai::UnicodeString &msg);
00760 
00767         AIAPI AIBoolean (*ChooseFromOSColorPicker) (const AIPoint &inLocation,
00768                 const AIRGBColor& inColor, AIRGBColor* outColor);
00769 
00786         AIAPI AIErr (*EvaluateExpression)(const ai::UnicodeString& expr, const AIExpressionOptions& options, ai::UnicodeString& evaluatedExpr,
00787                 AIBoolean & isChanged , AIDouble& numericValue);
00788     
00805     AIAPI AIErr (*EvaluateExpressionWithoutScale)(const ai::UnicodeString& expr, const AIExpressionOptions& options, ai::UnicodeString& evaluatedExpr,
00806                                       AIBoolean & isChanged , AIDouble& numericValue);
00807 
00823         AIAPI AIErr (*GetInputFromUser) ( const ai::UnicodeString &title, const ai::UnicodeString* messageText, const ai::UnicodeString &label, ai::UnicodeString& ioField, IsValidInputProc validator, void *userdata, ai::int32 maxInputChars);
00824 
00831         AIAPI AIErr (*CreateCursorResourceMgr)(SPPluginRef, AIResourceManagerHandle* inRscMgr);
00832 
00839         AIAPI AIErr (*SetCursor)(ai::int32 cursorID, AIResourceManagerHandle inRscMgr);
00840 
00846         AIAPI AIErr(*SetSVGCursor)(ai::int32 cursorID, AIResourceManagerHandle inRscMgr);
00847 
00852         AIAPI AIErr (*DisposeCursorResourceMgr)(AIResourceManagerHandle);
00853 
00857         AIAPI AIErr (*GetAILanguageCode)(ai::UnicodeString& lang);
00858     
00864         AIAPI AIReal (*GetMaximumScaleFactorOnSystem)();
00865 
00866 
00870         AIAPI AIReal(*GetArtToViewScaleFactor)(AIDocumentViewHandle view);
00871     
00877     AIAPI AIReal(*GetAppScaleFactor)();
00878 
00879 
00884         AIAPI AIErr(*LaunchFolder)(ai::FilePath folderPath);
00885 };
00886 
00887 
00888 
00889 /*
00890         Inline members
00891 */
00892         inline void AIFileDialogFilters::AddFilter(const ai::UnicodeString &desc)
00893         {
00894                 AddFilter(desc, ai::UnicodeString("*"));
00895         }
00896 
00897         inline void AIFileDialogFilters::AddFilter(const ai::UnicodeString &desc, const ai::UnicodeString &pattern)
00898         {
00899                 if (!desc.empty() && !pattern.empty())
00900                 {
00901                         const ai::UnicodeString::size_type len = filterStr.length();
00902                         if (len)
00903                                 filterStr.erase(len-1); // erase one null of the previous double null terminators
00904                         filterStr.append(desc);
00905                         filterStr.append(1, 0);
00906                         filterStr.append(pattern);
00907                         filterStr.append(2, 0);
00908                 }
00909         }
00910 
00911         inline const ai::UnicodeString &AIFileDialogFilters::GetFilter() const
00912         {
00913                 return filterStr;
00914         }
00915 
00916 #include "AIHeaderEnd.h"
00917 
00918 
00919 #endif