MBS Leopard Plugin
MBS Leopard Plugin Documentation
Christian Schmitz
July 16, 2017
2
0.1
Introduction
This is the PDF version of the documentation for the Xojo (Real Studio) Plug-in from Monkeybread Software
Germany. Plugin part: MBS Leopard Plugin
0.2
Content
• 1 List of all topics
3
• 2 List of all classes
51
• 3 List of all controls
55
• 4 List of all modules
57
• 5 All items in this plugin
59
• 19 List of Questions in the FAQ
465
• 20 The FAQ
475
Chapter 1
List of Topics
• 5 Calendar
59
– 5.1.1 class CalAlarmMBS
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
59
5.1.3 Constructor
5.1.4 triggerDateRelativeTo(currentdate as date) as date
5.1.6 absoluteTrigger as date
5.1.7 acknowledged as date
5.1.8 action as String
5.1.9 emailAddress as String
5.1.10 relatedTo as String
5.1.11 relativeTrigger as Double
5.1.12 sound as String
5.1.13 url as string
5.1.15 CalAlarmActionDisplay=”DISPLAY”
5.1.16 CalAlarmActionEmail=”EMAIL”
5.1.17 CalAlarmActionProcedure=”PROCEDURE”
5.1.18 CalAlarmActionSound=”AUDIO”
– 5.2.1 class CalAttendeeMBS
∗
∗
∗
∗
∗
∗
∗
∗
∗
60
60
61
61
61
61
62
62
62
62
63
63
63
63
64
5.2.3 Constructor
5.2.5 address as String
5.2.6 commonName as String
5.2.7 Handle as Integer
5.2.8 status as String
5.2.10 CalAttendeeStatusAccepted=”ACCEPTED”
5.2.11 CalAttendeeStatusDeclined=”DECLINED”
5.2.12 CalAttendeeStatusNeedsAction=”NEEDS-ACTION”
5.2.13 CalAttendeeStatusTentative=”TENTATIVE”
3
64
64
64
64
65
65
65
65
65
4
CHAPTER 1. LIST OF TOPICS
• 9 CoreAnimation
– 9.1.1 class CALayerMBS
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
9.1.3 addSublayer(layer as CALayerMBS)
9.1.4 available as boolean
9.1.5 Constructor
9.1.6 display
9.1.7 displayIfNeeded
9.1.8 layer as CALayerMBS
9.1.9 layoutIfNeeded
9.1.10 layoutSublayers
9.1.11 removeAllAnimations
9.1.12 removeFromSuperlayer
9.1.13 renderInContext(CGContextHandle as Integer) as boolean
9.1.14 renderInPicture(Pic as Picture) as boolean
9.1.15 setNeedsDisplay
9.1.16 setNeedsDisplayInRect(r as CGRectMBS)
9.1.17 setNeedsLayout
9.1.18 sublayers as CALayerMBS()
9.1.20 affineTransform as CGAffineTransformMBS
9.1.21 anchorPoint as CGRectMBS
9.1.22 anchorPointZ as Double
9.1.23 AutoresizingMask as Integer
9.1.24 backgroundColor as Variant
9.1.25 borderColor as Variant
9.1.26 borderWidth as Double
9.1.27 bounds as CGRectMBS
9.1.28 className as string
9.1.29 classPath as string
9.1.30 contents as Variant
9.1.31 contentsCenter as CGRectMBS
9.1.32 contentsRect as CGRectMBS
9.1.33 contentsScale as Double
9.1.34 cornerRadius as Double
9.1.35 DoubleSided as boolean
9.1.36 drawsAsynchronously as boolean
9.1.37 frame as CGRectMBS
9.1.38 Handle as Integer
9.1.39 Hidden as boolean
9.1.40 mask as CALayerMBS
9.1.41 masksToBounds as Boolean
9.1.42 minificationFilterBias as Double
155
155
156
156
156
156
157
157
157
157
158
158
158
158
159
159
159
159
160
160
160
161
161
161
162
162
162
162
163
163
163
164
164
165
165
165
166
166
166
166
167
5
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
9.1.43
9.1.44
9.1.45
9.1.46
9.1.47
9.1.48
9.1.49
9.1.50
9.1.51
9.1.52
9.1.53
9.1.54
9.1.55
9.1.56
9.1.57
9.1.58
9.1.59
9.1.60
9.1.62
9.1.63
9.1.64
9.1.65
9.1.66
9.1.67
9.1.68
9.1.69
9.1.70
9.1.71
9.1.72
modelLayer as CALayerMBS
needsDisplay as boolean
needsDisplayOnBoundsChange as boolean
needsLayout as boolean
opacity as Double
Opaque as boolean
position as CGRectMBS
preferredFrameSize as CGSizeMBS
presentationLayer as CALayerMBS
rasterizationScale as Double
shadowColor as Variant
shadowOffset as CGSizeMBS
shadowOpacity as Double
shadowPath as Variant
shadowRadius as Double
shouldRasterize as Boolean
superlayer as CALayerMBS
zPosition as Double
kCALayerBottomEdge = 4
kCALayerHeightSizable = 16
kCALayerLeftEdge = 1
kCALayerMaxXMargin = 4
kCALayerMaxYMargin = 32
kCALayerMinXMargin = 1
kCALayerMinYMargin = 8
kCALayerNotSizable = 0
kCALayerRightEdge = 2
kCALayerTopEdge = 8
kCALayerWidthSizable = 2
167
167
167
168
168
168
169
169
169
170
170
170
170
171
171
172
172
172
173
173
173
173
173
173
174
174
174
174
174
6
CHAPTER 1. LIST OF TOPICS
• 5 Calendar
59
– 5.3.1 class CalCalendarItemMBS
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
5.3.3 addAlarm(alarm as CalAlarmMBS)
5.3.4 addAlarms(alarms() as CalAlarmMBS)
5.3.5 alarms as CalAlarmMBS()
5.3.6 Constructor
5.3.7 hasAlarm as Boolean
5.3.8 nextAlarmDate as date
5.3.9 removeAlarm(alarm as CalAlarmMBS)
5.3.10 removeAlarms(alarms() as CalAlarmMBS)
5.3.11 setalarms(alarms() as CalAlarmMBS)
5.3.12 Show
5.3.14 calendar as CalCalendarMBS
5.3.15 dateStamp as date
5.3.16 Handle as Integer
5.3.17 notes as String
5.3.18 title as String
5.3.19 uid as String
5.3.20 URL as String
– 5.4.1 class CalCalendarMBS
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
5.4.3 Constructor
5.4.5 Color as NSColorMBS
5.4.6 Handle as Integer
5.4.7 isEditable as Boolean
5.4.8 notes as String
5.4.9 title as String
5.4.10 type as String
5.4.11 uid as String
5.4.13 CalCalendarTypeBirthday=”Birthday”
5.4.14 CalCalendarTypeCalDAV=”CalDAV”
5.4.15 CalCalendarTypeExchange=”Exchange”
5.4.16 CalCalendarTypeIMAP=”IMAP”
5.4.17 CalCalendarTypeLocal=”Local”
5.4.18 CalCalendarTypeSubscription=”Subscription”
– 5.5.1 class CalCalendarStoreMBS
∗
∗
∗
∗
∗
5.5.3
5.5.4
5.5.5
5.5.6
5.5.7
calendars as CalCalendarMBS()
calendarWithTitle(Title as string) as CalCalendarMBS
calendarWithUID(UID as string) as CalCalendarMBS
Constructor
events(StartDate as date, EndDate as date) as CalEventMBS()
66
66
66
66
66
67
67
67
67
67
67
68
68
68
68
69
70
71
72
72
73
73
74
74
74
74
75
75
76
76
76
76
76
77
78
78
79
79
79
7
∗ 5.5.8 events(StartDate as date, EndDate as date, calendar as CalCalendarMBS) as CalEventMBS()
80
∗ 5.5.9 events(StartDate as date, EndDate as date, calendars() as CalCalendarMBS) as CalEventMBS()
82
∗ 5.5.10 events(StartDate as date, EndDate as date, eventUID as string) as CalEventMBS() 82
∗ 5.5.11 events(StartDate as date, EndDate as date, eventUID as string, calendar as CalCalendarMBS) as CalEventMBS()
83
∗ 5.5.12 events(StartDate as date, EndDate as date, eventUID as string, calendars() as CalCalendarMBS) as CalEventMBS()
83
∗ 5.5.13 eventsMT(StartDate as date, EndDate as date, calendars() as CalCalendarMBS = nil)
as CalEventMBS()
83
∗ 5.5.14 eventWithUID(UID as string, occurrence as date) as CalEventMBS
84
∗ 5.5.15 removeCalendar(calendar as CalCalendarMBS, byref error as NSErrorMBS) as boolean
85
∗ 5.5.16 removeEvent(theEvent as CalEventMBS, span as Integer, byref error as NSErrorMBS)
as boolean
86
∗ 5.5.17 removeTask(task as CalTaskMBS, byref error as NSErrorMBS) as boolean
87
∗ 5.5.18 saveCalendar(calendar as CalCalendarMBS, byref error as NSErrorMBS) as boolean
87
∗ 5.5.19 saveEvent(theEvent as CalEventMBS, span as Integer, byref error as NSErrorMBS) as
boolean
88
∗ 5.5.20 saveTask(task as CalTaskMBS, byref error as NSErrorMBS) as boolean
88
∗ 5.5.21 tasks as CalTaskMBS()
89
∗ 5.5.22 tasks(calendar as CalCalendarMBS) as CalTaskMBS()
89
∗ 5.5.23 tasks(calendars() as CalCalendarMBS) as CalTaskMBS()
90
∗ 5.5.24 TasksCompletedSince(completedSince as date) as CalTaskMBS()
90
∗ 5.5.25 TasksCompletedSince(completedSince as date, calendar as CalCalendarMBS) as CalTaskMBS()
90
∗ 5.5.26 TasksCompletedSince(completedSince as date, calendars() as CalCalendarMBS) as
CalTaskMBS()
90
∗ 5.5.27 taskWithUID(UID as string) as CalTaskMBS
91
∗ 5.5.28 UncompletedTasks as CalTaskMBS()
91
∗ 5.5.29 UncompletedTasks(calendar as CalCalendarMBS) as CalTaskMBS()
91
∗ 5.5.30 UncompletedTasks(calendars() as CalCalendarMBS) as CalTaskMBS()
91
∗ 5.5.31 UncompletedTasksDueBefore(dueDate as date) as CalTaskMBS()
92
∗ 5.5.32 UncompletedTasksDueBefore(dueDate as date, calendar as CalCalendarMBS) as CalTaskMBS()
92
∗ 5.5.33 UncompletedTasksDueBefore(dueDate as date, calendars() as CalCalendarMBS) as
CalTaskMBS()
92
∗ 5.5.35 Handle as Integer
93
∗ 5.5.37 CalendarsChanged(Externally as boolean, InsertedRecords() as string, UpdatedRecords()
as string, DeletedRecords() as string)
93
∗ 5.5.38 EventsChanged(Externally as boolean, InsertedRecords() as string, UpdatedRecords()
as string, DeletedRecords() as string)
93
8
CHAPTER 1. LIST OF TOPICS
∗ 5.5.39 TasksChanged(Externally as boolean, InsertedRecords() as string, UpdatedRecords()
as string, DeletedRecords() as string)
94
∗ 5.5.41 CalSpanAllEvents=2
94
∗ 5.5.42 CalSpanFutureEvents=1
94
∗ 5.5.43 CalSpanThisEvent=0
95
– 5.6.1 class CalEventMBS
∗
∗
∗
∗
∗
∗
∗
∗
∗
5.6.3 attendees as CalAttendeeMBS()
5.6.4 Constructor
5.6.6 endDate as date
5.6.7 isAllDay as boolean
5.6.8 isDetached as boolean
5.6.9 location as string
5.6.10 occurrence as date
5.6.11 recurrenceRule as CalRecurrenceRuleMBS
5.6.12 startDate as date
– 5.7.1 class CalNthWeekDayMBS
∗ 5.7.3 Constructor
∗ 5.7.5 dayOfTheWeek as Integer
∗ 5.7.6 weekNumber as Integer
– 5.8.1 class CalRecurrenceEndMBS
∗
∗
∗
∗
∗
5.8.3
5.8.4
5.8.6
5.8.7
5.8.8
Constructor(endDate as date)
Constructor(occurrenceCount as Integer)
endDate as date
occurrenceCount as Integer
usesEndDate as boolean
– 5.9.1 class CalRecurrenceRuleMBS
∗
∗
∗
∗
∗
∗
∗
∗
∗
96
97
97
98
98
98
99
99
100
101
102
102
102
102
103
103
103
104
104
104
105
5.9.3 Constructor
106
5.9.4 daysOfTheMonth as Integer()
106
5.9.5 daysOfTheWeek as Integer()
106
5.9.6 initDailyRecurrence(interval as Integer, RecurrenceEnd as CalRecurrenceEndMBS) as
CalRecurrenceRuleMBS
106
5.9.7 initMonthlyRecurrence(interval as Integer, DayOfTheWeek as Integer, WeekOfTheMonth as Integer, RecurrenceEnd as CalRecurrenceEndMBS) as CalRecurrenceRuleMBS 107
5.9.8 initMonthlyRecurrence(interval as Integer, DaysOfTheMonth() as Integer, RecurrenceEnd
as CalRecurrenceEndMBS) as CalRecurrenceRuleMBS
107
5.9.9 initMonthlyRecurrence(interval as Integer, RecurrenceEnd as CalRecurrenceEndMBS)
as CalRecurrenceRuleMBS
108
5.9.10 initWeeklyRecurrence(interval as Integer, DaysOfTheWeek() as Integer, RecurrenceEnd
as CalRecurrenceEndMBS) as CalRecurrenceRuleMBS
108
5.9.11 initWeeklyRecurrence(interval as Integer, RecurrenceEnd as CalRecurrenceEndMBS)
as CalRecurrenceRuleMBS
109
9
∗ 5.9.12 initYearlyRecurrence(interval as Integer, DayOfTheWeek as Integer, WeekOfTheMonth
as Integer, MonthsOfTheYear() as Integer, RecurrenceEnd as CalRecurrenceEndMBS) as
CalRecurrenceRuleMBS
109
∗ 5.9.13 initYearlyRecurrence(interval as Integer, MonthsOfTheYear() as Integer, RecurrenceEnd
as CalRecurrenceEndMBS) as CalRecurrenceRuleMBS
110
∗ 5.9.14 initYearlyRecurrence(interval as Integer, RecurrenceEnd as CalRecurrenceEndMBS)
as CalRecurrenceRuleMBS
110
∗ 5.9.15 monthsOfTheYear as Integer()
112
∗ 5.9.16 nthWeekDaysOfTheMonth as CalNthWeekDayMBS()
112
∗ 5.9.18 firstDayOfTheWeek as Integer
112
∗ 5.9.19 Handle as Integer
113
∗ 5.9.20 recurrenceEnd as CalRecurrenceEndMBS
113
∗ 5.9.21 recurrenceInterval as Integer
113
∗ 5.9.22 recurrenceType as Integer
113
∗ 5.9.24 CalRecurrenceDaily=0
114
∗ 5.9.25 CalRecurrenceMonthly=2
114
∗ 5.9.26 CalRecurrenceWeekly=1
114
∗ 5.9.27 CalRecurrenceYearly=3
114
– 5.10.1 class CalTaskMBS
∗
∗
∗
∗
∗
∗
∗
∗
∗
5.10.3 Constructor
5.10.5 completedDate as date
5.10.6 dueDate as date
5.10.7 isCompleted as Boolean
5.10.8 priority as Integer
5.10.10 CalPriorityHigh=1
5.10.11 CalPriorityLow=9
5.10.12 CalPriorityMedium=5
5.10.13 CalPriorityNone=0
115
115
116
116
117
117
118
118
118
118
10
CHAPTER 1. LIST OF TOPICS
• 9 CoreAnimation
– 9.2.1 class CATransactionMBS
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
9.2.3 animationDuration as Double
9.2.4 available as boolean
9.2.5 begin
9.2.6 commit
9.2.7 Constructor
9.2.8 flush
9.2.9 kCATransactionAnimationDuration as string
9.2.10 kCATransactionDisableActions as string
9.2.11 setAnimationDuration(value as Double)
9.2.12 setValue(value as Variant, key as string)
9.2.13 valueForKey(key as string) as Variant
9.2.15 Handle as Integer
155
175
175
175
176
176
176
176
177
177
177
177
178
178
11
• 10 CoreGraphics
179
– 10.1.1 module CGWindowMBS
179
∗ 10.1.3 CreateWindowList(windowOption as Integer, WindowID as Integer = 0) as UInt32()
179
∗ 10.1.4 CreateWindowListCGImage(left as Double, top as Double, width as Double, height as
Double, windowOption as Integer, WindowID as Integer = 0, ImageOption as Integer = 0)
as Variant
180
∗ 10.1.5 CreateWindowListImage(left as Double, top as Double, width as Double, height as
Double, windowOption as Integer, WindowID as Integer = 0, ImageOption as Integer = 0)
as picture
180
∗ 10.1.6 GetWindowID(w as window) as Integer
182
∗ 10.1.7 GetWindowListInfo(windowOption as Integer, WindowID as Integer = 0) as dictionary()
182
∗ 10.1.9 kCGBackingStoreBuffered = 2
183
∗ 10.1.10 kCGBackingStoreNonretained = 1
183
∗ 10.1.11 kCGBackingStoreRetained = 0
183
∗ 10.1.12 kCGNullWindowID = 0
183
∗ 10.1.13 kCGWindowAlpha = ”kCGWindowAlpha”
184
∗ 10.1.14 kCGWindowBackingLocationVideoMemory = ”kCGWindowBackingLocationVideoMemory”
184
∗ 10.1.15 kCGWindowBounds = ”kCGWindowBounds”
184
∗ 10.1.16 kCGWindowImageBoundsIgnoreFraming = 1
185
∗ 10.1.17 kCGWindowImageDefault = 0
185
∗ 10.1.18 kCGWindowImageOnlyShadows = 4
185
∗ 10.1.19 kCGWindowImageShouldBeOpaque = 2
185
∗ 10.1.20 kCGWindowIsOnscreen = ”kCGWindowIsOnscreen”
185
∗ 10.1.21 kCGWindowLayer = ”kCGWindowLayer”
185
∗ 10.1.22 kCGWindowListExcludeDesktopElements = 16
186
∗ 10.1.23 kCGWindowListOptionAll = 0
186
∗ 10.1.24 kCGWindowListOptionIncludingWindow = 8
186
∗ 10.1.25 kCGWindowListOptionOnScreenAboveWindow = 2
186
∗ 10.1.26 kCGWindowListOptionOnScreenBelowWindow = 4
186
∗ 10.1.27 kCGWindowListOptionOnScreenOnly = 1
186
∗ 10.1.28 kCGWindowMemoryUsage = ”kCGWindowMemoryUsage”
187
∗ 10.1.29 kCGWindowName = ”kCGWindowName”
187
∗ 10.1.30 kCGWindowNumber = ”kCGWindowNumber”
187
∗ 10.1.31 kCGWindowOwnerName = ”kCGWindowOwnerName”
188
∗ 10.1.32 kCGWindowOwnerPID = ”kCGWindowOwnerPID”
188
∗ 10.1.33 kCGWindowSharingNone = 0
188
∗ 10.1.34 kCGWindowSharingReadOnly = 1
188
∗ 10.1.35 kCGWindowSharingReadWrite = 2
188
∗ 10.1.36 kCGWindowSharingState = ”kCGWindowSharingState”
188
∗ 10.1.37 kCGWindowStoreType = ”kCGWindowStoreType”
189
∗ 10.1.38 kCGWindowWorkspace = ”kCGWindowWorkspace”
189
12
CHAPTER 1. LIST OF TOPICS
• 6 Cocoa
119
– 6.1.1 control CocoaControlMBS
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
6.1.3 Available as Boolean
6.1.4 View as NSViewMBS
6.1.5 WantsFocus as Boolean
6.1.7 EnableMenuItems
6.1.8 GetView as NSViewMBS
6.1.9 MenuAction(HitItem as MenuItem) As Boolean
6.1.10 MouseDown(x as Integer, y as Integer, Modifiers as Integer) As Boolean
6.1.11 MouseDrag(x as Integer, y as Integer)
6.1.12 MouseUp(x as Integer, y as Integer)
6.1.13 ScaleFactorChanged(NewFactor as Double)
119
119
120
120
120
120
121
121
121
122
122
13
• 9 CoreAnimation
– 7.1.1 class Control
∗ 7.1.3 CALayerMBS as CALayerMBS
155
137
137
14
CHAPTER 1. LIST OF TOPICS
• 6 Cocoa
– 6.2.1 module DictionaryServiceMBS
∗
∗
∗
∗
119
123
6.2.3 GetTermRangeInString(text as string, offset as Integer=0) as boolean
123
6.2.4 RangeLength as Integer
124
6.2.5 RangePosition as Integer
124
6.2.6 Show(text as string, start as Integer = 0, length as Integer = 0, textOriginX as Double
= 0, textOriginY as Double = 0) as boolean
124
∗ 6.2.7 TextDefinition(text as string, position as Integer=0, length as Integer=0) as string 125
15
• 11 Files
– 11.1.1 class Folderitem
191
191
∗ 11.1.3 BackupIsItemExcludedMBS(byref excludeByPath as boolean) as boolean
191
∗ 11.1.4 BackupSetItemExcludedMBS(exclude as boolean, excludeByPath as boolean) as Integer
192
∗ 11.1.8 BackupItemExcludedMBS as boolean
193
∗ 11.1.9 MacQuarantinePropertiesMBS as MacQuarantinePropertiesMBS
194
16
CHAPTER 1. LIST OF TOPICS
• 18 QuickLook
– 11.1.1 class Folderitem
463
191
∗ 11.1.5 QuickLookMBS(MaxWidth as Integer = 500, MaxHeight as Integer = 500, IconMode
as Boolean = false, ScaleFactor as Double = 1.0) as picture
192
∗ 11.1.6 QuickLookMTMBS(MaxWidth as Integer = 500, MaxHeight as Integer = 500, IconMode as Boolean = false, ScaleFactor as Double = 1.0) as picture
193
17
• 12 Folder Change Watching
201
– 12.1.1 class FSEventsMBS
201
∗ 12.1.3 Available as Boolean
203
∗ 12.1.4 Constructor(DeviceToWatch as Integer, path as string, sinceWhen as UInt64, latency
as Double, flags as Integer)
203
∗ 12.1.5 Constructor(DeviceToWatch as Integer, paths() as string, sinceWhen as UInt64, latency as Double, flags as Integer)
205
∗ 12.1.6 Constructor(path as folderitem, sinceWhen as UInt64, latency as Double, flags as
Integer)
205
∗ 12.1.7 Constructor(path as string, sinceWhen as UInt64, latency as Double, flags as Integer)
206
∗ 12.1.8 Constructor(paths() as folderitem, sinceWhen as UInt64, latency as Double, flags as
Integer)
207
∗ 12.1.9 Constructor(paths() as string, sinceWhen as UInt64, latency as Double, flags as Integer)
207
∗ 12.1.10 Description as string
209
∗ 12.1.11 DeviceBeingWatched as Integer
209
∗ 12.1.12 ExclusionPaths as String()
209
∗ 12.1.13 FlushAsync as UInt64
209
∗ 12.1.14 FlushSync
209
∗ 12.1.15 GetAbsoluteTime(theDate as date) as Double
210
∗ 12.1.16 GetCurrentEventId as UInt64
210
∗ 12.1.17 GetDeviceID(volume as folderitem) as Integer
210
∗ 12.1.18 GetLastEventIdForDeviceBeforeTime(DeviceID as Integer, theTime as Double) as
UInt64
210
∗ 12.1.19 GetLatestEventId as UInt64
211
∗ 12.1.20 kFSEventStreamEventIdSinceNow as UInt64
211
∗ 12.1.21 PathsBeingWatched as String()
211
∗ 12.1.22 PurgeEventsForDeviceUpToEventId(DeviceID as Integer, EventID as UInt64) as boolean
211
∗ 12.1.23 SetExclusionPaths(paths() as String) as boolean
212
∗ 12.1.24 Show
212
∗ 12.1.25 Start as boolean
212
∗ 12.1.26 Stop
212
∗ 12.1.27 UUIDForDevice(DeviceID as Integer) as memoryblock
213
∗ 12.1.29 Handle as Integer
213
∗ 12.1.30 Running as Boolean
213
∗ 12.1.32 Callback(index as Integer, count as Integer, path as string, flags as Integer, eventID
as UInt64)
213
∗ 12.1.34 kFSEventStreamCreateFlagFileEvents = 16
214
∗ 12.1.35 kFSEventStreamCreateFlagIgnoreSelf = 8
214
∗ 12.1.36 kFSEventStreamCreateFlagMarkSelf = 32
214
18
CHAPTER 1. LIST OF TOPICS
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
12.1.37
12.1.38
12.1.39
12.1.40
12.1.41
12.1.42
12.1.43
12.1.44
12.1.45
12.1.46
12.1.47
12.1.48
12.1.49
12.1.50
12.1.51
12.1.52
12.1.53
12.1.54
12.1.55
12.1.56
12.1.57
12.1.58
12.1.59
12.1.60
12.1.61
12.1.62
12.1.63
kFSEventStreamCreateFlagNoDefer = 2
kFSEventStreamCreateFlagNone = 0
kFSEventStreamCreateFlagUseCFTypes = 1
kFSEventStreamCreateFlagWatchRoot = 4
kFSEventStreamEventFlagEventIdsWrapped = 8
kFSEventStreamEventFlagHistoryDone = 16
kFSEventStreamEventFlagItemChangeOwner = & h00004000
kFSEventStreamEventFlagItemCreated = & h00000100
kFSEventStreamEventFlagItemFinderInfoMod = & h00002000
kFSEventStreamEventFlagItemInodeMetaMod = & h00000400
kFSEventStreamEventFlagItemIsDir = & h00020000
kFSEventStreamEventFlagItemIsFile = & h00010000
kFSEventStreamEventFlagItemIsHardlink = & h00100000
kFSEventStreamEventFlagItemIsLastHardlink = & h00200000
kFSEventStreamEventFlagItemIsSymlink = & h00040000
kFSEventStreamEventFlagItemModified = & h00001000
kFSEventStreamEventFlagItemRemoved = & h00000200
kFSEventStreamEventFlagItemRenamed = & h00000800
kFSEventStreamEventFlagItemXattrMod = & h00008000
kFSEventStreamEventFlagKernelDropped = 4
kFSEventStreamEventFlagMount = 64
kFSEventStreamEventFlagMustScanSubDirs = 1
kFSEventStreamEventFlagNone = 0
kFSEventStreamEventFlagOwnEvent = & h00080000
kFSEventStreamEventFlagRootChanged = 32
kFSEventStreamEventFlagUnmount = 128
kFSEventStreamEventFlagUserDropped = 2
215
215
215
215
215
216
216
216
216
216
216
217
217
217
217
217
217
218
218
218
218
218
219
219
219
219
219
19
• 13 Image Capture
– 13.1.1 class ICCameraDeviceMBS
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
221
221
13.1.3 cancelDelete
221
13.1.4 cancelDownload
221
13.1.5 Constructor
222
13.1.6 contents as ICCameraItemMBS()
222
13.1.7 filesOfType(fileUTType as string) as ICCameraFileMBS()
222
13.1.8 ICCameraDeviceCanAcceptPTPCommands as string
222
13.1.9 ICCameraDeviceCanDeleteAllFiles as string
222
13.1.10 ICCameraDeviceCanDeleteOneFile as string
222
13.1.11 ICCameraDeviceCanReceiveFile as string
223
13.1.12 ICCameraDeviceCanSyncClock as string
223
13.1.13 ICCameraDeviceCanTakePicture as string
223
13.1.14 ICCameraDeviceCanTakePictureUsingShutterReleaseOnCamera as string
223
13.1.15 ICDeleteAfterSuccessfulDownload as string
223
13.1.16 ICDownloadsDirectoryURL as string
224
13.1.17 ICDownloadSidecarFiles as string
224
13.1.18 ICOverwrite as string
224
13.1.19 ICSaveAsFilename as string
224
13.1.20 ICSavedAncillaryFiles as string
224
13.1.21 ICSavedFilename as string
225
13.1.22 mediaFiles as ICCameraFileMBS()
225
13.1.23 requestDeleteFiles(files() as ICCameraFileMBS)
225
13.1.24 requestDisableTethering
225
13.1.25 requestDownloadFile(file as ICCameraFileMBS, options as dictionary = nil)
225
13.1.26 requestEnableTethering
225
13.1.27 requestReadDataFromFile(file as ICCameraFileMBS, offset as UInt64, Length as
UInt64)
226
13.1.28 requestSendPTPCommand(command as MemoryBlock, dataOut as MemoryBlock)
226
13.1.29 requestSyncClock
226
13.1.30 requestTakePicture
226
13.1.31 requestUploadFile(file as folderitem, options as dictionary = nil)
226
13.1.33 batteryLevel as Integer
227
13.1.34 batteryLevelAvailable as Boolean
227
13.1.35 contentCatalogPercentCompleted as Integer
227
13.1.36 isAccessRestrictedAppleDevice as Boolean
227
13.1.37 mountPoint as String
228
13.1.38 tetheredCaptureEnabled as Boolean
228
13.1.39 timeOffset as Double
228
– 13.2.1 class ICCameraFileMBS
229
20
CHAPTER 1. LIST OF TOPICS
∗
∗
∗
∗
∗
13.2.3
13.2.4
13.2.6
13.2.7
13.2.8
Constructor
sidecarFiles as ICCameraFileMBS()
Duration as Double
FileSize as UInt64
Orientation as Integer
– 13.3.1 class ICCameraFolderMBS
∗ 13.3.3 Constructor
∗ 13.3.4 contents as ICCameraItemMBS()
– 13.4.1 class ICCameraItemMBS
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
13.4.3 Constructor
13.4.5 addedAfterContentCatalogCompleted as Boolean
13.4.6 CreationDate as Date
13.4.7 Device as ICCameraDeviceMBS
13.4.8 FileSystemPath as String
13.4.9 Handle as Integer
13.4.10 InTemporaryStore as Boolean
13.4.11 largeThumbnailIfAvailable as Variant
13.4.12 Locked as Boolean
13.4.13 MetadataIfAvailable as Dictionary
13.4.14 ModificationDate as Date
13.4.15 Name as String
13.4.16 ParentFolder as ICCameraFolderMBS
13.4.17 ptpObjectHandle as Integer
13.4.18 Raw as Boolean
13.4.19 thumbnailIfAvailable as Variant
13.4.20 UserData as Dictionary
13.4.21 UTI as String
– 13.5.1 class ICDeviceBrowserMBS
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
13.5.3 Constructor
13.5.4 Destructor
13.5.5 devices as ICDeviceMBS()
13.5.6 Start
13.5.7 Stop
13.5.9 browsedDeviceTypeMask as Integer
13.5.10 Browsing as Boolean
13.5.11 Handle as Integer
13.5.12 preferredDevice as ICDeviceMBS
13.5.14 DeviceDidChangeName(device as ICDeviceMBS)
13.5.15 DeviceDidChangeSharingState(device as ICDeviceMBS)
13.5.16 DidAddDevice(device as ICDeviceMBS, moreComing as boolean)
13.5.17 DidEnumerateLocalDevices
229
229
229
229
230
231
231
231
232
232
232
232
233
233
233
233
233
234
234
234
234
234
235
235
235
235
235
237
237
237
237
237
238
238
238
238
238
239
239
239
239
21
∗ 13.5.18 DidRemoveDevice(device as ICDeviceMBS, moreGoing as boolean)
∗ 13.5.19 RequestsSelectDevice(device as ICDeviceMBS)
– 13.6.1 class ICDeviceMBS
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
240
240
241
13.6.3 capabilities as Variant()
241
13.6.4 Constructor
241
13.6.5 ICButtonTypeCopy as string
241
13.6.6 ICButtonTypeMail as string
241
13.6.7 ICButtonTypePrint as string
242
13.6.8 ICButtonTypeScan as string
242
13.6.9 ICButtonTypeTransfer as string
242
13.6.10 ICButtonTypeWeb as string
242
13.6.11 ICDeviceCanEjectOrDisconnect as string
242
13.6.12 ICDeviceLocationDescriptionBluetooth as string
242
13.6.13 ICDeviceLocationDescriptionFireWire as string
243
13.6.14 ICDeviceLocationDescriptionMassStorage as string
243
13.6.15 ICDeviceLocationDescriptionUSB as string
243
13.6.16 ICLocalizedStatusNotificationKey as string
243
13.6.17 ICStatusCodeKey as string
243
13.6.18 ICStatusNotificationKey as string
243
13.6.19 ICTransportTypeBluetooth as string
244
13.6.20 ICTransportTypeFireWire as string
244
13.6.21 ICTransportTypeMassStorage as string
244
13.6.22 ICTransportTypeTCPIP as string
244
13.6.23 ICTransportTypeUSB as string
244
13.6.24 requestCloseSession
244
13.6.25 requestEjectOrDisconnect
245
13.6.26 requestOpenSession
245
13.6.27 requestSendMessage(messageCode as UInt32, data as MemoryBlock, maxReturnedDataSize as UInt64)
245
13.6.28 requestYield
245
13.6.30 AutolaunchApplicationPath as String
246
13.6.31 BonjourServiceType as String
246
13.6.32 BskonjourServiceName as String
246
13.6.33 ButtonPressed as String
246
13.6.34 canDeleteAllFiles as Boolean
246
13.6.35 canDeleteOneFile as Boolean
246
13.6.36 canEject as Boolean
247
13.6.37 canReceiveFile as Boolean
247
13.6.38 canSyncClock as Boolean
247
13.6.39 canTakePicture as Boolean
247
13.6.40 fwGUID as Int64
247
22
CHAPTER 1. LIST OF TOPICS
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
13.6.41
13.6.42
13.6.43
13.6.44
13.6.45
13.6.46
13.6.47
13.6.48
13.6.49
13.6.50
13.6.51
13.6.52
13.6.53
13.6.54
13.6.55
13.6.56
13.6.57
13.6.58
13.6.59
13.6.60
13.6.61
13.6.62
13.6.63
13.6.65
13.6.66
13.6.67
13.6.68
13.6.69
13.6.70
13.6.71
13.6.72
13.6.73
13.6.74
13.6.75
13.6.76
13.6.77
Handle as Integer
HasConfigurableWiFiInterface as Boolean
HasOpenSession as Boolean
Icon as Variant
IconPath as String
IPAddress as String
IsRemote as Boolean
IsShared as Boolean
LocationDescription as String
ModuleExecutableArchitecture as Integer
ModulePath as String
ModuleVersion as String
Name as String
PersistentIDString as String
ProductKind as String
SerialNumberString as String
TransportType as String
type as Integer
usbLocationID as Integer
usbProductID as Integer
usbVendorID as Integer
UserData as Dictionary
UUIDString as String
ICDeviceLocationTypeBluetooth = & h00000800
ICDeviceLocationTypeBonjour = & h00000400
ICDeviceLocationTypeLocal = & h00000100
ICDeviceLocationTypeMaskBluetooth = & h00000800
ICDeviceLocationTypeMaskBonjour = & h00000400
ICDeviceLocationTypeMaskLocal = & h00000100
ICDeviceLocationTypeMaskRemote = & h0000FE00
ICDeviceLocationTypeMaskShared = & h00000200
ICDeviceLocationTypeShared = & h00000200
ICDeviceTypeCamera = & h00000001
ICDeviceTypeMaskCamera = & h00000001
ICDeviceTypeMaskScanner = & h00000002
ICDeviceTypeScanner = & h00000002
– 13.7.1 class ICScannerBandDataMBS
∗
∗
∗
∗
13.7.3
13.7.5
13.7.6
13.7.7
Constructor
bigEndian as Boolean
bitsPerComponent as UInt64
bitsPerPixel as UInt64
248
248
248
248
248
248
249
249
249
249
250
250
250
250
250
251
251
251
251
252
252
252
252
252
253
253
253
253
253
253
253
254
254
254
254
254
255
255
255
255
255
23
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
13.7.8 bytesPerRow as UInt64
13.7.9 colorSyncProfilePath as String
13.7.10 dataBuffer as Memoryblock
13.7.11 dataNumRows as UInt64
13.7.12 dataSize as UInt64
13.7.13 dataStartRow as UInt64
13.7.14 fullImageHeight as UInt64
13.7.15 fullImageWidth as UInt64
13.7.16 Handle as Integer
13.7.17 numComponents as UInt64
13.7.18 pixelDataType as Integer
– 13.8.1 class ICScannerDeviceMBS
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
13.8.3 availableFunctionalUnitTypes as Integer()
13.8.4 cancelScan
13.8.5 Constructor
13.8.6 ICScannerStatusRequestsOverviewScan as string
13.8.7 ICScannerStatusWarmingUp as string
13.8.8 ICScannerStatusWarmUpDone as string
13.8.9 requestOverviewScan
13.8.10 requestScan
13.8.11 requestSelectFunctionalUnit(type as Integer)
13.8.13 documentName as String
13.8.14 documentUTI as String
13.8.15 downloadsDirectory as String
13.8.16 downloadsFolder as FolderItem
13.8.17 maxMemoryBandSize as UInt64
13.8.18 selectedFunctionalUnit as ICScannerFunctionalUnitMBS
13.8.19 transferMode as Integer
13.8.21 ICScannerTransferModeFileBased = 0
13.8.22 ICScannerTransferModeMemoryBased = 1
– 13.9.1 class ICScannerFeatureBooleanMBS
∗ 13.9.3 Constructor
∗ 13.9.5 value as Boolean
– 13.10.1 class ICScannerFeatureEnumerationMBS
∗
∗
∗
∗
∗
∗
13.10.3
13.10.4
13.10.5
13.10.6
13.10.8
13.10.9
Constructor
menuItemLabels as String()
menuItemLabelsTooltips as String()
values as Variant()
currentValue as Variant
defaultValue as Variant
– 13.11.1 class ICScannerFeatureMBS
256
256
256
256
256
256
257
257
257
257
257
258
258
258
258
258
259
259
259
259
259
260
260
260
260
260
261
261
261
261
262
262
262
263
263
263
263
263
264
264
265
24
CHAPTER 1. LIST OF TOPICS
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
13.11.3 Constructor
13.11.5 Handle as Integer
13.11.6 humanReadableName as String
13.11.7 internalName as String
13.11.8 tooltip as String
13.11.9 type as Integer
13.11.11 ICScannerFeatureTypeBoolean = 2
13.11.12 ICScannerFeatureTypeEnumeration = 0
13.11.13 ICScannerFeatureTypeRange = 1
13.11.14 ICScannerFeatureTypeTemplate = 3
– 13.12.1 class ICScannerFeatureRangeMBS
∗
∗
∗
∗
∗
∗
13.12.3
13.12.5
13.12.6
13.12.7
13.12.8
13.12.9
Constructor
currentValue as Double
defaultValue as Double
maxValue as Double
minValue as Double
stepSize as Double
– 13.13.1 class ICScannerFeatureTemplateMBS
∗ 13.13.3 Constructor
∗ 13.13.4 targets as ICScannerFeatureMBS()
– 13.14.1 class ICScannerFunctionalUnitDocumentFeederMBS
∗
∗
∗
∗
∗
∗
∗
13.14.3 Constructor
13.14.5 documentLoaded as Boolean
13.14.6 duplexScanningEnabled as Boolean
13.14.7 evenPageOrientation as Integer
13.14.8 oddPageOrientation as Integer
13.14.9 reverseFeederPageOrder as Boolean
13.14.10 supportsDuplexScanning as Boolean
– 13.15.1 class ICScannerFunctionalUnitFlatbedMBS
∗ 13.15.3 Constructor
– 13.16.1 class ICScannerFunctionalUnitMBS
∗
∗
∗
∗
∗
∗
∗
∗
∗
13.16.3 Constructor
13.16.4 templates as ICScannerFeatureTemplateMBS()
13.16.5 vendorFeatures as ICScannerFeatureMBS()
13.16.7 acceptsThresholdForBlackAndWhiteScanning as Boolean
13.16.8 bitDepth as Integer
13.16.9 canPerformOverviewScan as Boolean
13.16.10 defaultThresholdForBlackAndWhiteScanning as Integer
13.16.11 documentSize as NSSizeMBS
13.16.12 documentType as Integer
265
265
265
265
266
266
266
266
266
267
268
268
268
268
269
269
269
270
270
270
271
271
271
271
272
272
273
273
274
274
275
275
275
275
275
276
276
276
276
276
25
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
13.16.13
13.16.14
13.16.15
13.16.16
13.16.17
13.16.18
13.16.19
13.16.20
13.16.21
13.16.22
13.16.23
13.16.24
13.16.25
13.16.26
13.16.27
13.16.28
13.16.29
13.16.30
13.16.31
13.16.32
13.16.33
13.16.34
13.16.35
13.16.36
13.16.37
13.16.39
13.16.40
13.16.41
13.16.42
13.16.43
13.16.44
13.16.45
13.16.46
13.16.47
13.16.48
13.16.49
13.16.50
13.16.51
13.16.52
13.16.53
13.16.54
13.16.55
measurementUnit as Integer
nativeXResolution as Integer
nativeYResolution as Integer
overviewImage as Variant
overviewResolution as Integer
overviewScanInProgress as Boolean
physicalSize as NSSizeMBS
pixelDataType as Integer
preferredResolutions as NSIndexSetMBS
preferredScaleFactors as NSIndexSetMBS
resolution as Integer
scaleFactor as Integer
scanArea as NSRectMBS
scanAreaOrientation as Integer
scanInProgress as Boolean
scanProgressPercentDone as Double
state as Integer
supportedBitDepths as NSIndexSetMBS
supportedDocumentTypes as NSIndexSetMBS
supportedMeasurementUnits as NSIndexSetMBS
supportedResolutions as NSIndexSetMBS
supportedScaleFactors as NSIndexSetMBS
thresholdForBlackAndWhiteScanning as Integer
type as Integer
usesThresholdForBlackAndWhiteScanning as Boolean
ICScannerBitDepth16Bits = 16
ICScannerBitDepth1Bit = 1
ICScannerBitDepth8Bits = 8
ICScannerColorDataFormatTypeChunky = 0
ICScannerColorDataFormatTypePlanar = 1
ICScannerDocumentType10 = 25
ICScannerDocumentType10R = 67
ICScannerDocumentType110 = 72
ICScannerDocumentType11R = 69
ICScannerDocumentType12R = 70
ICScannerDocumentType135 = 76
ICScannerDocumentType2A0 = 18
ICScannerDocumentType3R = 61
ICScannerDocumentType4A0 = 17
ICScannerDocumentType4R = 62
ICScannerDocumentType5R = 63
ICScannerDocumentType6R = 64
277
277
277
277
277
278
278
278
278
278
279
279
279
279
280
280
280
280
281
281
281
281
281
282
282
282
282
282
282
283
283
283
283
283
284
284
284
284
284
284
284
285
26
CHAPTER 1. LIST OF TOPICS
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
13.16.56
13.16.57
13.16.58
13.16.59
13.16.60
13.16.61
13.16.62
13.16.63
13.16.64
13.16.65
13.16.66
13.16.67
13.16.68
13.16.69
13.16.70
13.16.71
13.16.72
13.16.73
13.16.74
13.16.75
13.16.76
13.16.77
13.16.78
13.16.79
13.16.80
13.16.81
13.16.82
13.16.83
13.16.84
13.16.85
13.16.86
13.16.87
13.16.88
13.16.89
13.16.90
13.16.91
13.16.92
13.16.93
13.16.94
13.16.95
13.16.96
13.16.97
ICScannerDocumentType8R = 65
ICScannerDocumentTypeA0 = 19
ICScannerDocumentTypeA1 = 20
ICScannerDocumentTypeA2 = 21
ICScannerDocumentTypeA3 = 11
ICScannerDocumentTypeA4 = 1
ICScannerDocumentTypeA5 = 5
ICScannerDocumentTypeA6 = 13
ICScannerDocumentTypeA7 = 22
ICScannerDocumentTypeA8 = 23
ICScannerDocumentTypeA9 = 24
ICScannerDocumentTypeAPSC = 74
ICScannerDocumentTypeAPSH = 73
ICScannerDocumentTypeAPSP = 75
ICScannerDocumentTypeB5 = 2
ICScannerDocumentTypeBusinessCard = 53
ICScannerDocumentTypeC0 = 44
ICScannerDocumentTypeC1 = 45
ICScannerDocumentTypeC10 = 51
ICScannerDocumentTypeC2 = 46
ICScannerDocumentTypeC3 = 47
ICScannerDocumentTypeC4 = 14
ICScannerDocumentTypeC5 = 15
ICScannerDocumentTypeC6 = 16
ICScannerDocumentTypeC7 = 48
ICScannerDocumentTypeC8 = 49
ICScannerDocumentTypeC9 = 50
ICScannerDocumentTypeDefault = 0
ICScannerDocumentTypeE = 60
ICScannerDocumentTypeISOB0 = 26
ICScannerDocumentTypeISOB1 = 27
ICScannerDocumentTypeISOB10 = 33
ICScannerDocumentTypeISOB2 = 28
ICScannerDocumentTypeISOB3 = 12
ICScannerDocumentTypeISOB4 = 6
ICScannerDocumentTypeISOB5 = 29
ICScannerDocumentTypeISOB6 = 7
ICScannerDocumentTypeISOB7 = 30
ICScannerDocumentTypeISOB8 = 31
ICScannerDocumentTypeISOB9 = 32
ICScannerDocumentTypeJISB0 = 34
ICScannerDocumentTypeJISB1 = 35
285
285
285
285
285
285
286
286
286
286
286
286
286
287
287
287
287
287
287
287
288
288
288
288
288
288
288
289
289
289
289
289
289
289
290
290
290
290
290
290
290
291
27
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
13.16.98 ICScannerDocumentTypeJISB10 = 43
13.16.99 ICScannerDocumentTypeJISB2 = 36
13.16.100 ICScannerDocumentTypeJISB3 = 37
13.16.101 ICScannerDocumentTypeJISB4 = 38
13.16.102 ICScannerDocumentTypeJISB6 = 39
13.16.103 ICScannerDocumentTypeJISB7 = 40
13.16.104 ICScannerDocumentTypeJISB8 = 41
13.16.105 ICScannerDocumentTypeJISB9 = 42
13.16.106 ICScannerDocumentTypeLF = 78
13.16.107 ICScannerDocumentTypeMF = 77
13.16.108 ICScannerDocumentTypeS10R = 68
13.16.109 ICScannerDocumentTypeS12R = 71
13.16.110 ICScannerDocumentTypeS8R = 66
13.16.111 ICScannerDocumentTypeUSExecutive = 10
13.16.112 ICScannerDocumentTypeUSLedger = 9
13.16.113 ICScannerDocumentTypeUSLegal = 4
13.16.114 ICScannerDocumentTypeUSLetter = 3
13.16.115 ICScannerDocumentTypeUSStatement = 52
13.16.116 ICScannerFunctionalUnitStateOverviewScanInProgress = 4
13.16.117 ICScannerFunctionalUnitStateReady = 1
13.16.118 ICScannerFunctionalUnitStateScanInProgress = 2
13.16.119 ICScannerFunctionalUnitTypeDocumentFeeder = 3
13.16.120 ICScannerFunctionalUnitTypeFlatbed = 0
13.16.121 ICScannerFunctionalUnitTypeNegativeTransparency = 2
13.16.122 ICScannerFunctionalUnitTypePositiveTransparency = 1
13.16.123 ICScannerMeasurementUnitCentimeters = 1
13.16.124 ICScannerMeasurementUnitInches = 0
13.16.125 ICScannerMeasurementUnitPicas = 2
13.16.126 ICScannerMeasurementUnitPixels = 5
13.16.127 ICScannerMeasurementUnitPoints = 3
13.16.128 ICScannerMeasurementUnitTwips = 4
13.16.129 ICScannerPixelDataTypeBW = 0
13.16.130 ICScannerPixelDataTypeCIEXYZ = 8
13.16.131 ICScannerPixelDataTypeCMY = 4
13.16.132 ICScannerPixelDataTypeCMYK = 5
13.16.133 ICScannerPixelDataTypeGray = 1
13.16.134 ICScannerPixelDataTypePalette = 3
13.16.135 ICScannerPixelDataTypeRGB = 2
13.16.136 ICScannerPixelDataTypeYUV = 6
13.16.137 ICScannerPixelDataTypeYUVK = 7
– 13.17.1 class ICScannerFunctionalUnitNegativeTransparencyMBS
291
291
291
291
291
291
292
293
293
293
293
293
293
293
294
294
294
294
294
294
294
295
295
295
295
295
295
295
296
296
296
296
296
296
296
297
297
297
297
297
298
28
CHAPTER 1. LIST OF TOPICS
∗ 13.17.3 Constructor
– 13.18.1 class ICScannerFunctionalUnitPositiveTransparencyMBS
∗ 13.18.3 Constructor
– 13.19.1 control IKCameraDeviceViewControlMBS
298
299
299
300
∗ 13.19.3 View as IKCameraDeviceViewMBS
300
∗ 13.19.5 BoundsChanged
300
∗ 13.19.6 DidDownloadFile(CameraFile as ICCameraFileMBS, URL as string, File as folderItem,
data as MemoryBlock, error as NSErrorMBS)
300
∗ 13.19.7 DidEncounterError(Error as NSErrorMBS)
300
∗ 13.19.8 EnableMenuItems
301
∗ 13.19.9 FrameChanged
301
∗ 13.19.10 GotFocus
301
∗ 13.19.11 LostFocus
301
∗ 13.19.12 MenuAction(HitItem as MenuItem) As Boolean
301
∗ 13.19.13 MouseDown(x as Integer, y as Integer, Modifiers as Integer) As Boolean
301
∗ 13.19.14 MouseDrag(x as Integer, y as Integer)
302
∗ 13.19.15 MouseUp(x as Integer, y as Integer)
302
∗ 13.19.16 ScaleFactorChanged(NewFactor as Double)
302
∗ 13.19.17 SelectionDidChange
302
– 13.20.1 class IKCameraDeviceViewMBS
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
303
13.20.3 Constructor
303
13.20.4 Constructor(Handle as Integer)
303
13.20.5 Constructor(left as Double, top as Double, width as Double, height as Double) 304
13.20.6 deleteSelectedItems
304
13.20.7 downloadAllItems
304
13.20.8 downloadSelectedItems
304
13.20.9 rotateLeft
304
13.20.10 rotateRight
305
13.20.11 selectIndexes(indexes as NSIndexSetMBS, extend as boolean)
305
13.20.13 cameraDevice as ICCameraDeviceMBS
305
13.20.14 canDeleteSelectedItems as Boolean
305
13.20.15 canDownloadSelectedItems as Boolean
305
13.20.16 canRotateSelectedItemsLeft as Boolean
305
13.20.17 canRotateSelectedItemsRight as Boolean
306
13.20.18 displaysDownloadsDirectoryControl as Boolean
306
13.20.19 displaysPostProcessApplicationControl as Boolean
306
13.20.20 downloadAllControlLabel as String
306
13.20.21 downloadsDirectory as String
306
13.20.22 downloadSelectedControlLabel as String
306
13.20.23 downloadsFolder as FolderItem
307
13.20.24 hasDisplayModeIcon as Boolean
307
29
∗
∗
∗
∗
∗
∗
∗
13.20.25 hasDisplayModeTable as Boolean
307
13.20.26 iconSize as Integer
307
13.20.27 mode as Integer
307
13.20.28 postProcessApplication as String
308
13.20.29 selectedIndexes as NSIndexSetMBS
308
13.20.30 transferMode as Integer
308
13.20.32 DidDownloadFile(CameraFile as ICCameraFileMBS, URL as string, File as folderItem,
data as MemoryBlock, error as NSErrorMBS)
308
∗ 13.20.33 DidEncounterError(Error as NSErrorMBS)
308
∗ 13.20.34 SelectionDidChange
309
∗ 13.20.36 IKCameraDeviceViewDisplayModeIcon = 1
309
∗ 13.20.37 IKCameraDeviceViewDisplayModeTable = 0
309
∗ 13.20.38 IKCameraDeviceViewTransferModeFileBased = 0
309
∗ 13.20.39 IKCameraDeviceViewTransferModeMemoryBased = 1
309
– 13.21.1 control IKDeviceBrowserViewControlMBS
310
∗ 13.21.3 View as IKDeviceBrowserViewMBS
310
∗ 13.21.5 BoundsChanged
310
∗ 13.21.6 DidEncounterError(error as NSErrorMBS)
310
∗ 13.21.7 EnableMenuItems
310
∗ 13.21.8 FrameChanged
311
∗ 13.21.9 GotFocus
311
∗ 13.21.10 LostFocus
311
∗ 13.21.11 MenuAction(HitItem as MenuItem) As Boolean
311
∗ 13.21.12 MouseDown(x as Integer, y as Integer, Modifiers as Integer) As Boolean
311
∗ 13.21.13 MouseDrag(x as Integer, y as Integer)
312
∗ 13.21.14 MouseUp(x as Integer, y as Integer)
312
∗ 13.21.15 ScaleFactorChanged(NewFactor as Double)
312
∗ 13.21.16 SelectionDidChange(device as ICDeviceMBS)
312
– 13.22.1 class IKDeviceBrowserViewMBS
313
∗ 13.22.3 Constructor
313
∗ 13.22.4 Constructor(Handle as Integer)
313
∗ 13.22.5 Constructor(left as Double, top as Double, width as Double, height as Double) 314
∗ 13.22.7 displaysLocalCameras as Boolean
314
∗ 13.22.8 displaysLocalScanners as Boolean
314
∗ 13.22.9 displaysNetworkCameras as Boolean
314
∗ 13.22.10 displaysNetworkScanners as Boolean
315
∗ 13.22.11 mode as Integer
315
∗ 13.22.12 selectedDevice as ICDeviceMBS
315
∗ 13.22.14 DidEncounterError(error as NSErrorMBS)
315
∗ 13.22.15 SelectionDidChange(device as ICDeviceMBS)
315
∗ 13.22.17 IKDeviceBrowserViewDisplayModeIcon = 2
315
∗ 13.22.18 IKDeviceBrowserViewDisplayModeOutline = 1
316
∗ 13.22.19 IKDeviceBrowserViewDisplayModeTable = 0
316
30
CHAPTER 1. LIST OF TOPICS
• 14 ImageKit
– 14.1.1 class IKImageBrowserCellMBS
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
14.1.3 cellState as Integer
14.1.4 Constructor
14.1.5 frame as NSRectMBS
14.1.6 IKImageBrowserCellBackgroundLayer as string
14.1.7 IKImageBrowserCellForegroundLayer as string
14.1.8 IKImageBrowserCellPlaceHolderLayer as string
14.1.9 IKImageBrowserCellSelectionLayer as string
14.1.10 imageAlignment as Integer
14.1.11 imageBrowserView as IKImageBrowserViewMBS
14.1.12 imageContainerFrame as NSRectMBS
14.1.13 imageFrame as NSRectMBS
14.1.14 indexOfRepresentedItem as Integer
14.1.15 isSelected as boolean
14.1.16 layerForType(type as string) as CALayerMBS
14.1.17 opacity as Double
14.1.18 representedItem as Variant
14.1.19 selectionFrame as NSRectMBS
14.1.20 subtitleFrame as NSRectMBS
14.1.21 titleFrame as NSRectMBS
14.1.23 Handle as Integer
14.1.25 IKImageStateInvalid = 1
14.1.26 IKImageStateNoImage = 0
14.1.27 IKImageStateReady = 2
– 14.2.1 class IKImageBrowserItemMBS
341
341
341
341
342
342
342
342
342
343
343
343
343
344
344
344
344
344
345
345
345
346
346
346
346
347
∗ 14.2.3 Constructor(imageUID as string, imageRepresentationType as string, imageRepresentation as Variant, imageVersion as Integer = 1, imageTitle as string = ””, imageSubtitle as
string = ””, isSelectable as boolean = true)
347
∗ 14.2.4 ItemWithCGImage(imageUID as string, Image as Variant, imageVersion as Integer =
1, imageTitle as string = ””, imageSubtitle as string = ””, isSelectable as boolean = true) as
IKImageBrowserItemMBS
347
∗ 14.2.5 ItemWithData(imageUID as string, Data as Memoryblock, imageVersion as Integer =
1, imageTitle as string = ””, imageSubtitle as string = ””, isSelectable as boolean = true) as
IKImageBrowserItemMBS
347
∗ 14.2.6 ItemWithFile(imageUID as string, file as folderitem, imageVersion as Integer = 1,
imageTitle as string = ””, imageSubtitle as string = ””, isSelectable as boolean = true) as
IKImageBrowserItemMBS
347
∗ 14.2.7 ItemWithNSImage(imageUID as string, Image as NSImageMBS, imageVersion as Integer = 1, imageTitle as string = ””, imageSubtitle as string = ””, isSelectable as boolean =
true) as IKImageBrowserItemMBS
348
31
∗ 14.2.8 ItemWithPath(imageUID as string, path as string, imageVersion as Integer = 1, imageTitle as string = ””, imageSubtitle as string = ””, isSelectable as boolean = true) as
IKImageBrowserItemMBS
348
∗ 14.2.9 ItemWithURL(imageUID as string, URL as string, imageVersion as Integer = 1, imageTitle as string = ””, imageSubtitle as string = ””, isSelectable as boolean = true) as
IKImageBrowserItemMBS
348
∗ 14.2.11 Handle as Integer
348
∗ 14.2.12 imageRepresentation as Variant
348
∗ 14.2.13 imageRepresentationType as string
349
∗ 14.2.14 imageSubtitle as string
349
∗ 14.2.15 imageTitle as string
349
∗ 14.2.16 imageUID as string
349
∗ 14.2.17 imageVersion as Integer
349
∗ 14.2.18 isSelectable as boolean
350
– 14.3.1 control IKImageBrowserViewControlMBS
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
351
14.3.3 Scrollview as NSScrollViewMBS
351
14.3.4 View as IKImageBrowserViewMBS
351
14.3.6 backgroundWasRightClickedWithEvent(e as NSEventMBS)
351
14.3.7 BoundsChanged
352
14.3.8 cellWasDoubleClickedAtIndex(index as Integer)
352
14.3.9 cellWasRightClickedAtIndex(index as Integer, e as NSEventMBS)
352
14.3.10 concludeDragOperation(sender as NSDraggingInfoMBS)
352
14.3.11 draggingEnded(sender as NSDraggingInfoMBS)
353
14.3.12 draggingEntered(sender as NSDraggingInfoMBS) as Integer
353
14.3.13 draggingExited(sender as NSDraggingInfoMBS)
354
14.3.14 draggingSourceOperationMaskForLocal(flag as boolean) as Integer
354
14.3.15 draggingUpdated(sender as NSDraggingInfoMBS) as Integer
354
14.3.16 EnableMenuItems
355
14.3.17 FrameChanged
355
14.3.18 GotFocus
355
14.3.19 groupAtIndex(index as Integer) as Dictionary
356
14.3.20 itemAtIndex(index as Integer) as IKImageBrowserItemMBS
356
14.3.21 LostFocus
356
14.3.22 MenuAction(HitItem as MenuItem) As Boolean
356
14.3.23 MouseDown(x as Integer, y as Integer, Modifiers as Integer) As Boolean
357
14.3.24 MouseDrag(x as Integer, y as Integer)
357
14.3.25 MouseUp(x as Integer, y as Integer)
357
14.3.26 moveItemsAtIndexes(indexes as NSIndexSetMBS, destinationIndex as Integer) as
boolean
358
∗ 14.3.27 numberOfGroups as Integer
358
∗ 14.3.28 numberOfItems as Integer
358
∗ 14.3.29 performDragOperation(sender as NSDraggingInfoMBS) as boolean
359
32
CHAPTER 1. LIST OF TOPICS
∗
∗
∗
∗
∗
∗
∗
14.3.30 prepareForDragOperation(sender as NSDraggingInfoMBS) as boolean
359
14.3.31 removeItemsAtIndexes(indexes as NSIndexSetMBS)
359
14.3.32 ScaleFactorChanged(NewFactor as Double)
360
14.3.33 selectionDidChange
360
14.3.34 updateDraggingItemsForDrag(sender as NSDraggingInfoMBS)
360
14.3.35 wantsPeriodicDraggingUpdates as boolean
361
14.3.36 writeItemsAtIndexes(indexes as NSIndexSetMBS, pasteboard as NSPasteboardMBS)
as Integer
361
– 14.4.1 class IKImageBrowserViewMBS
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
14.4.3 cellForItemAtIndex(index as Integer) as IKImageBrowserCellMBS
14.4.4 collapseGroupAtIndex(index as Integer)
14.4.5 columnIndexesInRect(rect as NSRectMBS) as NSIndexSetMBS
14.4.6 Constructor
14.4.7 Constructor(Handle as Integer)
14.4.8 Constructor(left as Double, top as Double, width as Double, height as Double)
14.4.9 Destructor
14.4.10 dropOperation as Integer
14.4.11 expandGroupAtIndex(index as Integer)
14.4.12 getValue(name as String) as Variant
14.4.13 IKImageBrowserBackgroundColorKey as string
14.4.14 IKImageBrowserCellsHighlightedTitleAttributesKey as string
14.4.15 IKImageBrowserCellsOutlineColorKey as string
14.4.16 IKImageBrowserCellsSubtitleAttributesKey as string
14.4.17 IKImageBrowserCellsTitleAttributesKey as string
14.4.18 IKImageBrowserCGImageRepresentationType as string
14.4.19 IKImageBrowserCGImageSourceRepresentationType as string
14.4.20 IKImageBrowserGroupBackgroundColorKey as string
14.4.21 IKImageBrowserGroupFooterLayer as string
14.4.22 IKImageBrowserGroupHeaderLayer as string
14.4.23 IKImageBrowserGroupRangeKey as string
14.4.24 IKImageBrowserGroupStyleKey as string
14.4.25 IKImageBrowserGroupTitleKey as string
14.4.26 IKImageBrowserIconRefPathRepresentationType as string
14.4.27 IKImageBrowserIconRefRepresentationType as string
14.4.28 IKImageBrowserNSBitmapImageRepresentationType as string
14.4.29 IKImageBrowserNSDataRepresentationType as string
14.4.30 IKImageBrowserNSImageRepresentationType as string
14.4.31 IKImageBrowserNSURLRepresentationType as string
14.4.32 IKImageBrowserPathRepresentationType as string
14.4.33 IKImageBrowserPDFPageRepresentationType as string
14.4.34 IKImageBrowserQCCompositionPathRepresentationType as string
362
362
362
362
363
363
363
364
364
364
364
365
365
365
365
366
366
366
366
367
367
367
367
368
368
368
368
368
368
369
369
369
369
33
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
14.4.35 IKImageBrowserQCCompositionRepresentationType as string
369
14.4.36 IKImageBrowserQTMoviePathRepresentationType as string
369
14.4.37 IKImageBrowserQTMovieRepresentationType as string
370
14.4.38 IKImageBrowserQuickLookPathRepresentationType as string
370
14.4.39 IKImageBrowserSelectionColorKey as string
370
14.4.40 indexAtLocationOfDroppedItem as Integer
370
14.4.41 indexOfItemAtPoint(point as NSPointMBS) as Integer
370
14.4.42 isGroupExpandedAtIndex(index as Integer) as boolean
371
14.4.43 itemFrameAtIndex(index as Integer) as NSRectMBS
371
14.4.44 newCellForRepresentedItem(item as IKImageBrowserItemMBS) as IKImageBrowserCellMBS
371
14.4.45 numberOfColumns as Integer
371
14.4.46 numberOfRows as Integer
371
14.4.47 rectOfColumn(columnIndex as Integer) as NSRectMBS
372
14.4.48 rectOfRow(rowIndex as Integer) as NSRectMBS
372
14.4.49 reloadData
372
14.4.50 rowIndexesInRect(rect as NSRectMBS) as NSIndexSetMBS
372
14.4.51 scrollIndexToVisible(index as Integer)
372
14.4.52 selectionIndexes as NSIndexSetMBS
373
14.4.53 setDropIndex(index as Integer, operation as Integer)
373
14.4.54 setSelectionIndexes(indexes as NSIndexSetMBS, extendSelection as boolean = false)
373
14.4.55 setValue(name as String, value as Variant)
373
14.4.56 visibleItemIndexes as NSIndexSetMBS
374
14.4.58 allowsDroppingOnItems as boolean
374
14.4.59 allowsEmptySelection as boolean
374
14.4.60 allowsMultipleSelection as boolean
374
14.4.61 allowsReordering as boolean
374
14.4.62 animates as boolean
375
14.4.63 backgroundLayer as CALayerMBS
375
14.4.64 canControlQuickLookPanel as boolean
375
14.4.65 cellSize as NSSizeMBS
375
14.4.66 cellsStyleMask as Integer
376
14.4.67 constrainsToOriginalSize as boolean
376
14.4.68 contentResizingMask as Integer
376
14.4.69 foregroundLayer as CALayerMBS
376
14.4.70 intercellSpacing as NSSizeMBS
376
14.4.71 zoomValue as Double
377
14.4.73 backgroundWasRightClickedWithEvent(e as NSEventMBS)
377
14.4.74 cellWasDoubleClickedAtIndex(index as Integer)
377
14.4.75 cellWasRightClickedAtIndex(index as Integer, e as NSEventMBS)
378
14.4.76 concludeDragOperation(sender as NSDraggingInfoMBS)
378
34
CHAPTER 1. LIST OF TOPICS
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
14.4.77 draggingEnded(sender as NSDraggingInfoMBS)
378
14.4.78 draggingEntered(sender as NSDraggingInfoMBS) as Integer
379
14.4.79 draggingExited(sender as NSDraggingInfoMBS)
379
14.4.80 draggingSourceOperationMaskForLocal(flag as boolean) as Integer
379
14.4.81 draggingUpdated(sender as NSDraggingInfoMBS) as Integer
380
14.4.82 groupAtIndex(index as Integer) as Dictionary
381
14.4.83 itemAtIndex(index as Integer) as IKImageBrowserItemMBS
381
14.4.84 moveItemsAtIndexes(indexes as NSIndexSetMBS, destinationIndex as Integer) as
boolean
382
14.4.85 numberOfGroups as Integer
382
14.4.86 numberOfItems as Integer
382
14.4.87 performDragOperation(sender as NSDraggingInfoMBS) as boolean
383
14.4.88 prepareForDragOperation(sender as NSDraggingInfoMBS) as boolean
383
14.4.89 removeItemsAtIndexes(indexes as NSIndexSetMBS)
383
14.4.90 selectionDidChange
384
14.4.91 updateDraggingItemsForDrag(sender as NSDraggingInfoMBS)
384
14.4.92 wantsPeriodicDraggingUpdates as boolean
385
14.4.93 writeItemsAtIndexes(indexes as NSIndexSetMBS, pasteboard as NSPasteboardMBS)
as Integer
385
14.4.95 IKCellsStyleNone = 0
385
14.4.96 IKCellsStyleOutlined = 2
385
14.4.97 IKCellsStyleShadowed = 1
386
14.4.98 IKCellsStyleSubtitled = 8
386
14.4.99 IKCellsStyleTitled = 4
386
14.4.100 IKGroupBezelStyle = 0
386
14.4.101 IKGroupDisclosureStyle = 1
386
14.4.102 IKImageBrowserDropBefore = 1
386
14.4.103 IKImageBrowserDropOn = 0
387
– 14.5.1 class IKImageEditPanelMBS
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
14.5.3 Constructor
14.5.4 reloadData
14.5.6 LastImage as Picture
14.5.8 Changed(pic as picture, CGImageHandle as Integer, metaData as dictionary)
14.5.9 hasAdjustMode as Boolean
14.5.10 hasDetailsMode as Boolean
14.5.11 hasEffectsMode as Boolean
14.5.12 Image as picture
14.5.13 imageProperties as Dictionary
14.5.14 thumbnailWithMaximumSize(Width as Double, Height as Double) as picture
– 14.6.1 class IKPictureTakerMBS
∗ 14.6.3 Available as boolean
388
388
388
388
389
389
389
389
390
390
390
391
391
35
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
14.6.4 beginPictureTaker as boolean
14.6.5 beginPictureTakerSheet(parent as NSWindowMBS) as boolean
14.6.6 beginPictureTakerSheet(parent as window) as boolean
14.6.7 Constructor
14.6.8 CropAreaSizeHeight as Double
14.6.9 CropAreaSizeWidth as Double
14.6.10 outputImage as NSImageMBS
14.6.11 OutputImageMaxSizeKeyHeight as Double
14.6.12 OutputImageMaxSizeKeyWidth as Double
14.6.13 popUpRecentsMenuForView(parent as NSViewMBS) as boolean
14.6.14 runModal as Integer
14.6.15 SetCropAreaSize(width as Double, height as Double)
14.6.16 SetOutputImageMaxSize(width as Double, height as Double)
14.6.18 AllowsEditing as boolean
14.6.19 AllowsFileChoosing as boolean
14.6.20 AllowsVideoCapture as boolean
14.6.21 InformationalText as NSAttributedStringMBS
14.6.22 InformationalText as string
14.6.23 inputImage as NSImageMBS
14.6.24 mirroring as boolean
14.6.25 RemainOpenAfterValidate as boolean
14.6.26 ShowAddressBookPicture as boolean
14.6.27 ShowEffects as boolean
14.6.28 ShowEmptyPicture as NSImageMBS
14.6.29 ShowRecentPicture as boolean
14.6.30 UpdateRecentPicture as boolean
14.6.32 Finished(returnCode as Integer)
391
392
392
393
393
393
393
393
393
393
394
395
395
395
395
395
395
396
396
396
397
397
397
397
397
397
398
36
CHAPTER 1. LIST OF TOPICS
• 13 Image Capture
221
– 13.23.1 control IKScannerDeviceViewControlMBS
317
∗ 13.23.3 View as IKScannerDeviceViewMBS
317
∗ 13.23.5 BoundsChanged
317
∗ 13.23.6 DidEncounterError(error as NSErrorMBS)
317
∗ 13.23.7 DidScanToBandData(data as ICScannerBandDataMBS, scanInfo as Dictionary, error
as NSErrorMBS)
317
∗ 13.23.8 DidScanToURL(url as String, file as FolderItem, fileData as MemoryBlock, error as
NSErrorMBS)
318
∗ 13.23.9 EnableMenuItems
318
∗ 13.23.10 FrameChanged
318
∗ 13.23.11 GotFocus
318
∗ 13.23.12 LostFocus
318
∗ 13.23.13 MenuAction(HitItem as MenuItem) As Boolean
318
∗ 13.23.14 MouseDown(x as Integer, y as Integer, Modifiers as Integer) As Boolean
319
∗ 13.23.15 MouseDrag(x as Integer, y as Integer)
319
∗ 13.23.16 MouseUp(x as Integer, y as Integer)
319
∗ 13.23.17 ScaleFactorChanged(NewFactor as Double)
319
– 13.24.1 class IKScannerDeviceViewMBS
320
∗ 13.24.3 Constructor
320
∗ 13.24.4 Constructor(Handle as Integer)
320
∗ 13.24.5 Constructor(left as Double, top as Double, width as Double, height as Double) 321
∗ 13.24.7 displaysDownloadsDirectoryControl as Boolean
321
∗ 13.24.8 displaysPostProcessApplicationControl as Boolean
321
∗ 13.24.9 documentName as String
321
∗ 13.24.10 downloadsDirectory as String
322
∗ 13.24.11 downloadsFolder as FolderItem
322
∗ 13.24.12 hasDisplayModeAdvanced as Boolean
322
∗ 13.24.13 hasDisplayModeSimple as Boolean
322
∗ 13.24.14 mode as Integer
322
∗ 13.24.15 overviewControlLabel as String
323
∗ 13.24.16 postProcessApplication as String
323
∗ 13.24.17 scanControlLabel as String
323
∗ 13.24.18 scannerDevice as ICScannerDeviceMBS
323
∗ 13.24.19 transferMode as Integer
323
∗ 13.24.21 DidEncounterError(error as NSErrorMBS)
323
∗ 13.24.22 DidScanToBandData(data as ICScannerBandDataMBS, scanInfo as Dictionary, error as NSErrorMBS)
324
∗ 13.24.23 DidScanToURL(url as String, file as FolderItem, fileData as MemoryBlock, error as
NSErrorMBS)
324
∗ 13.24.25 IKScannerDeviceViewDisplayModeAdvanced = 1
324
∗ 13.24.26 IKScannerDeviceViewDisplayModeSimple = 0
324
∗ 13.24.27 IKScannerDeviceViewTransferModeFileBased = 0
324
∗ 13.24.28 IKScannerDeviceViewTransferModeMemoryBased = 1
325
37
• 14 ImageKit
341
– 14.7.1 class IKSlideshowMBS
399
∗ 14.7.3 addFile(file as folderitem, name as string=””)
399
∗ 14.7.4 addImage(image as NSImageMBS, name as string=””)
399
∗ 14.7.5 addPage(page as Variant, name as string=””)
399
∗ 14.7.6 autoPlayDelay as Double
400
∗ 14.7.7 Available as boolean
400
∗ 14.7.8 canExportToApplication(applicationBundleIdentifier as string) as boolean
400
∗ 14.7.9 exportSlideshowItems(applicationBundleIdentifier as string)
400
∗ 14.7.10 indexOfCurrentSlideshowItem as Integer
401
∗ 14.7.11 ItemCount as Integer
401
∗ 14.7.12 reloadData
401
∗ 14.7.13 reloadSlideshowItemAtIndex(index as Integer)
401
∗ 14.7.14 removeItem(index as Integer)
401
∗ 14.7.15 removeItems
402
∗ 14.7.16 runSlideshow
402
∗ 14.7.17 setFile(index as Integer, file as folderitem, name as string=””)
402
∗ 14.7.18 setImage(index as Integer, image as NSImageMBS, name as string=””)
402
∗ 14.7.19 setPage(index as Integer, page as Variant, name as string=””)
402
∗ 14.7.20 stopSlideshow
402
∗ 14.7.22 AudioFile as Folderitem
403
∗ 14.7.23 PDFDisplayBox as Integer
403
∗ 14.7.24 PDFDisplayMode as Integer
403
∗ 14.7.25 PDFDisplaysAsBook as Boolean
403
∗ 14.7.26 ScreenIndex as Integer
404
∗ 14.7.27 StartIndex as Integer
404
∗ 14.7.28 StartPaused as Boolean
404
∗ 14.7.29 WrapAround as Boolean
404
∗ 14.7.31 canExportSlideshowItemAtIndex(index as Integer, applicationBundleIdentifier as string)
as boolean
405
∗ 14.7.32 slideshowDidChangeCurrentIndex(newIndex as Integer)
405
∗ 14.7.33 slideshowDidStop
405
∗ 14.7.34 slideshowWillStart
405
∗ 14.7.36 iPhotoBundleIdentifier=”com.apple.iPhoto”
405
∗ 14.7.37 kPDFDisplayBoxArtBox=4
405
∗ 14.7.38 kPDFDisplayBoxBleedBox=2
406
∗ 14.7.39 kPDFDisplayBoxCropBox=1
406
∗ 14.7.40 kPDFDisplayBoxMediaBox=0
406
∗ 14.7.41 kPDFDisplayBoxTrimBox=3
406
∗ 14.7.42 kPDFDisplaySinglePage=0
406
∗ 14.7.43 kPDFDisplaySinglePageContinuous=1
406
∗ 14.7.44 kPDFDisplayTwoUp=2
406
∗ 14.7.45 kPDFDisplayTwoUpContinuous=3
406
38
CHAPTER 1. LIST OF TOPICS
• 13 Image Capture
– 13.25.1 class ImageCaptureEventsMBS
221
326
∗ 13.25.3 Handle as Integer
326
∗ 13.25.5 cameraDeviceDidAddItem(camera as ICCameraDeviceMBS, item as ICCameraItemMBS)
326
∗ 13.25.6 cameraDeviceDidAddItems(camera as ICCameraDeviceMBS, items() as ICCameraItemMBS)
326
∗ 13.25.7 cameraDeviceDidBecomeReadyWithCompleteContentCatalog(camera as ICCameraDeviceMBS)
327
∗ 13.25.8 cameraDeviceDidChangeCapability(camera as ICCameraDeviceMBS)
327
∗ 13.25.9 cameraDeviceDidCompleteDeleteFilesWithError(camera as ICCameraDeviceMBS, error as NSErrorMBS)
327
∗ 13.25.10 cameraDeviceDidDownloadFile(file as ICCameraFileMBS, error as NSErrorMBS,
options as Dictionary, device as ICCameraDeviceMBS)
327
∗ 13.25.11 cameraDeviceDidReadData(data as Memoryblock, file as ICCameraFileMBS, error
as NSErrorMBS, device as ICCameraDeviceMBS)
327
∗ 13.25.12 cameraDeviceDidReceiveDownloadProgressForFile(file as ICCameraFileMBS, downloadedBytes as UInt64, maxBytes as UInt64)
328
∗ 13.25.13 cameraDeviceDidReceiveMetadataForItem(camera as ICCameraDeviceMBS, item as
ICCameraItemMBS)
328
∗ 13.25.14 cameraDeviceDidReceivePTPEvent(camera as ICCameraDeviceMBS, eventData as
MemoryBlock)
328
∗ 13.25.15 cameraDeviceDidReceiveThumbnailForItem(camera as ICCameraDeviceMBS, item
as ICCameraItemMBS)
328
∗ 13.25.16 cameraDeviceDidRemoveItem(camera as ICCameraDeviceMBS, item as ICCameraItemMBS)
328
∗ 13.25.17 cameraDeviceDidRemoveItems(camera as ICCameraDeviceMBS, items() as ICCameraItemMBS)
328
∗ 13.25.18 cameraDeviceDidRenameItems(camera as ICCameraDeviceMBS, items() as ICCameraItemMBS)
329
∗ 13.25.19 cameraDeviceDidSendPTPCommand(command as Memoryblock, data as Memoryblock, response as MemoryBlock, error as NSErrorMBS, device as ICCameraDeviceMBS)
329
∗ 13.25.20 cameraDeviceDidUploadFile(fileURL as string, file as FolderItem, error as NSErrorMBS, device as ICCameraDeviceMBS)
329
∗ 13.25.21 cameraDeviceViewDidDownloadFile(cameraDeviceView as IKCameraDeviceViewMBS,
CameraFile as ICCameraFileMBS, URL as string, File as folderItem, data as MemoryBlock,
error as NSErrorMBS)
329
∗ 13.25.22 cameraDeviceViewDidEncounterError(cameraDeviceView as IKCameraDeviceViewMBS,
error as NSErrorMBS)
329
∗ 13.25.23 cameraDeviceViewSelectionDidChange(cameraDeviceView as IKCameraDeviceViewMBS)
330
∗ 13.25.24 deviceBrowserDeviceDidChangeName(browser as ICDeviceBrowserMBS, device as
ICDeviceMBS)
330
39
∗ 13.25.25 deviceBrowserDeviceDidChangeSharingState(browser as ICDeviceBrowserMBS, device as ICDeviceMBS)
330
∗ 13.25.26 deviceBrowserDidAddDevice(browser as ICDeviceBrowserMBS, device as ICDeviceMBS,
moreComing as boolean)
330
∗ 13.25.27 deviceBrowserDidEnumerateLocalDevices(browser as ICDeviceBrowserMBS) 330
∗ 13.25.28 deviceBrowserDidRemoveDevice(browser as ICDeviceBrowserMBS, device as ICDeviceMBS, moreGoing as boolean)
331
∗ 13.25.29 deviceBrowserRequestsSelectDevice(browser as ICDeviceBrowserMBS, device as ICDeviceMBS)
331
∗ 13.25.30 deviceBrowserViewDidEncounterError(deviceBrowserView as IKDeviceBrowserViewMBS,
error as NSErrorMBS)
331
∗ 13.25.31 deviceBrowserViewSelectionDidChange(deviceBrowserView as IKDeviceBrowserViewMBS,
device as ICDeviceMBS)
331
∗ 13.25.32 deviceDidBecomeReady(device as ICDeviceMBS)
331
∗ 13.25.33 deviceDidChangeName(device as ICDeviceMBS)
332
∗ 13.25.34 deviceDidChangeSharingState(device as ICDeviceMBS)
332
∗ 13.25.35 deviceDidCloseSessionWithError(device as ICDeviceMBS, error as NSErrorMBS)
332
∗ 13.25.36 deviceDidEncounterError(device as ICDeviceMBS, error as NSErrorMBS)
332
∗ 13.25.37 deviceDidOpenSessionWithError(device as ICDeviceMBS, error as NSErrorMBS)
332
∗ 13.25.38 deviceDidReceiveButtonPress(device as ICDeviceMBS, buttonType as String) 333
∗ 13.25.39 deviceDidReceiveCustomNotification(device as ICDeviceMBS, notification as Dictionary, data as Memoryblock)
333
∗ 13.25.40 deviceDidReceiveStatusInformation(device as ICDeviceMBS, status as Dictionary)
333
∗ 13.25.41 deviceDidRemove(device as ICDeviceMBS)
333
∗ 13.25.42 deviceDidSendMessage(messageCode as UInt32, data as Memoryblock, error as
NSErrorMBS, device as ICDeviceMBS)
334
∗ 13.25.43 scannerDeviceDidBecomeAvailable(scanner as ICScannerDeviceMBS)
334
∗ 13.25.44 scannerDeviceDidCompleteOverviewScanWithError(scanner as ICScannerDeviceMBS,
error as NSErrorMBS)
334
∗ 13.25.45 scannerDeviceDidCompleteScanWithError(scanner as ICScannerDeviceMBS, error
as NSErrorMBS)
334
∗ 13.25.46 scannerDeviceDidScanToBandData(scanner as ICScannerDeviceMBS, Data as ICScannerBandDataMBS)
334
∗ 13.25.47 scannerDeviceDidScanToURL(scanner as ICScannerDeviceMBS, URL as string, file
as folderitem, data as MemoryBlock)
335
∗ 13.25.48 scannerDeviceDidSelectFunctionalUnit(scanner as ICScannerDeviceMBS, functionalUnit as Variant, Error as NSErrorMBS)
335
∗ 13.25.49 scannerDeviceViewDidEncounterError(scannerDeviceView as IKScannerDeviceViewMBS,
error as NSErrorMBS)
335
∗ 13.25.50 scannerDeviceViewDidScanToBandData(scannerDeviceView as IKScannerDeviceViewMBS,
data as ICScannerBandDataMBS, scanInfo as Dictionary, error as NSErrorMBS)
335
40
CHAPTER 1. LIST OF TOPICS
∗ 13.25.51 scannerDeviceViewDidScanToURL(scannerDeviceView as IKScannerDeviceViewMBS,
url as String, file as FolderItem, fileData as MemoryBlock, error as NSErrorMBS)
336
∗ 13.25.53 ICReturnCommunicationTimedOut = -9923
336
∗ 13.25.54 ICReturnDeleteFilesCanceled = -9942
336
∗ 13.25.55 ICReturnDeleteFilesFailed = -9941
336
∗ 13.25.56 ICReturnDeviceFailedToCloseSession = -9928
336
∗ 13.25.57 ICReturnDeviceFailedToOpenSession = -9927
336
∗ 13.25.58 ICReturnDeviceFailedToTakePicture = -9944
337
∗ 13.25.59 ICReturnDeviceIsPasscodeLocked = -9943
337
∗ 13.25.60 ICReturnDeviceSoftwareInstallationCanceled = -9948
337
∗ 13.25.61 ICReturnDeviceSoftwareInstallationCompleted = -9947
337
∗ 13.25.62 ICReturnDeviceSoftwareInstallationFailed = -9949
337
∗ 13.25.63 ICReturnDeviceSoftwareIsBeingInstalled = -9946
337
∗ 13.25.64 ICReturnDeviceSoftwareNotAvailable = -9950
337
∗ 13.25.65 ICReturnDeviceSoftwareNotInstalled = -9945
338
∗ 13.25.66 ICReturnDownloadCanceled = -9937
338
∗ 13.25.67 ICReturnDownloadFailed = -9934
338
∗ 13.25.68 ICReturnFailedToCompletePassThroughCommand = -9936
338
∗ 13.25.69 ICReturnFailedToCompleteSendMessageRequest = -9940
338
∗ 13.25.70 ICReturnFailedToDisabeTethering = -9939
338
∗ 13.25.71 ICReturnFailedToEnabeTethering = -9938
338
∗ 13.25.72 ICReturnInvalidParam = -9922
339
∗ 13.25.73 ICReturnReceivedUnsolicitedScannerErrorInfo = -9933
339
∗ 13.25.74 ICReturnReceivedUnsolicitedScannerStatusInfo = -9932
339
∗ 13.25.75 ICReturnScannerFailedToCompleteOverviewScan = -9930
339
∗ 13.25.76 ICReturnScannerFailedToCompleteScan = -9931
339
∗ 13.25.77 ICReturnScannerFailedToSelectFunctionalUnit = -9929
339
∗ 13.25.78 ICReturnScannerInUseByLocalUser = -9925
339
∗ 13.25.79 ICReturnScannerInUseByRemoteUser = -9926
340
∗ 13.25.80 ICReturnScanOperationCanceled = -9924
340
∗ 13.25.81 ICReturnSuccess = 0
340
∗ 13.25.82 ICReturnUploadFailed = -9935
340
41
• 15 JavaScript
407
– 15.1.1 class JSClassMBS
∗
∗
∗
∗
∗
15.1.3
15.1.4
15.1.6
15.1.7
15.1.8
Constructor
NewObject as JSObjectMBS
context as JSContextMBS
Handle as Integer
Tag as Variant
– 15.2.1 class JSContextMBS
407
407
407
408
408
408
409
∗ 15.2.3 CheckScriptSyntax(script as string, sourceURL as String, startingLineNumber as Integer = 1, byref JSException as JSValueMBS) as Boolean
409
∗ 15.2.4 Constructor
410
∗ 15.2.5 EvaluateScript(script as string, sourceURL as String, thisObject as JSValueMBS, startingLineNumber as Integer = 1, byref JSException as JSValueMBS) as JSValueMBS
410
∗ 15.2.6 GarbageCollect
411
∗ 15.2.7 NewArray(arguments() as JSValueMBS, byref JSException as JSValueMBS) as JSObjectMBS
411
∗ 15.2.8 NewDate(arguments() as JSValueMBS, byref JSException as JSValueMBS) as JSObjectMBS
412
∗ 15.2.9 NewError(arguments() as JSValueMBS, byref JSException as JSValueMBS) as JSObjectMBS
412
∗ 15.2.10 NewFunction(name as string) as JSObjectMBS
413
∗ 15.2.11 NewFunction(name as string, parameterNames() as string, Body as String, SourceURL
as string = ””, startingLineNumber as Integer = 0, byref JSException as JSValueMBS) as
JSValueMBS
413
∗ 15.2.12 NewObject as JSObjectMBS
414
∗ 15.2.13 NewRegExp(arguments() as JSValueMBS, byref JSException as JSValueMBS) as
JSObjectMBS
414
∗ 15.2.14 valueWithBool(value as boolean) as JSValueMBS
415
∗ 15.2.15 valueWithDouble(value as Double) as JSValueMBS
415
∗ 15.2.16 valueWithJSON(JSON as string) as JSValueMBS
415
∗ 15.2.17 valueWithNull as JSValueMBS
416
∗ 15.2.18 valueWithString(value as string) as JSValueMBS
416
∗ 15.2.19 valueWithUndefined as JSValueMBS
416
∗ 15.2.21 globalObject as JSObjectMBS
417
∗ 15.2.22 Handle as Integer
417
∗ 15.2.23 Name as String
417
∗ 15.2.24 Tag as Variant
418
∗ 15.2.26 FunctionCalled(functionObject as JSObjectMBS, thisObject as JSObjectMBS, arguments() as JSValueMBS, byref JSException as JSValueMBS) as JSValueMBS
418
– 15.3.1 class JSObjectMBS
419
∗ 15.3.3 CallAsConstructor(arguments() as JSValueMBS, byref JSException as JSValueMBS)
as JSValueMBS
419
42
CHAPTER 1. LIST OF TOPICS
∗ 15.3.4 CallAsFunction(thisObject as JSValueMBS, arguments() as JSValueMBS, byref JSException as JSValueMBS) as JSValueMBS
419
∗ 15.3.5 Constructor
420
∗ 15.3.6 DeleteProperty(name as string, byref JSException as JSValueMBS) as boolean 420
∗ 15.3.7 GetProperty(name as string, byref JSException as JSValueMBS) as JSValueMBS 420
∗ 15.3.8 GetPropertyAtIndex(propertyIndex as Integer, byref JSException as JSValueMBS) as
JSValueMBS
421
∗ 15.3.9 HasProperty(name as string) as boolean
422
∗ 15.3.10 PropertyNames as String()
422
∗ 15.3.11 SetProperty(name as string, value as JSValueMBS, byref JSException as JSValueMBS)
422
∗ 15.3.12 SetPropertyAtIndex(propertyIndex as Integer, value as JSValueMBS, byref JSException as JSValueMBS)
423
∗ 15.3.14 isConstructor as Boolean
423
∗ 15.3.15 isFunction as Boolean
424
∗ 15.3.16 Prototype as JSValueMBS
424
– 15.4.1 class JSValueMBS
425
∗ 15.4.3 Constructor
425
∗ 15.4.4 DoubleValue(byref JSException as JSValueMBS) as Double
425
∗ 15.4.5 IsEqual(OtherValue as JSValueMBS, byref JSException as JSValueMBS) as boolean
425
∗ 15.4.6 IsInstanceOfConstructor(ConstructorFunction as JSObjectMBS, byref JSException as
JSValueMBS) as boolean
426
∗ 15.4.7 IsObjectOfClass(ClassObject as JSValueMBS) as boolean
426
∗ 15.4.8 IsStrictEqual(OtherValue as JSValueMBS) as boolean
426
∗ 15.4.9 JSONString(indent as Integer = 0, byref JSException as JSValueMBS) as string 427
∗ 15.4.10 ObjectValue(byref JSException as JSValueMBS) as JSValueMBS
427
∗ 15.4.11 StringValue(byref JSException as JSValueMBS) as string
428
∗ 15.4.13 booleanValue as Boolean
428
∗ 15.4.14 context as JSContextMBS
428
∗ 15.4.15 doubleValue as Double
428
∗ 15.4.16 Handle as Integer
429
∗ 15.4.17 isArray as Boolean
429
∗ 15.4.18 isBoolean as Boolean
429
∗ 15.4.19 isDate as Boolean
430
∗ 15.4.20 isNull as Boolean
430
∗ 15.4.21 isNumber as Boolean
431
∗ 15.4.22 isObject as Boolean
431
∗ 15.4.23 isString as Boolean
432
∗ 15.4.24 isUndefined as Boolean
432
∗ 15.4.25 JSONString as string
432
∗ 15.4.26 StringValue as String
433
43
∗
∗
∗
∗
∗
∗
∗
∗
15.4.27
15.4.28
15.4.30
15.4.31
15.4.32
15.4.33
15.4.34
15.4.35
Tag as Variant
Type as Integer
kJSTypeBoolean = 2
kJSTypeNull = 1
kJSTypeNumber = 3
kJSTypeObject = 5
kJSTypeString = 4
kJSTypeUndefined = 0
433
433
434
435
435
435
436
436
44
CHAPTER 1. LIST OF TOPICS
• 16 Login Items
437
– 16.1.1 class LSSharedFileListItemMBS
437
∗ 16.1.3 DisplayName as string
437
∗ 16.1.4 Icon as Variant
438
∗ 16.1.5 ID as UInt32
438
∗ 16.1.6 Resolve(flags as UInt32) as folderitem
438
∗ 16.1.7 ResolveURL(flags as UInt32) as string
439
∗ 16.1.9 Handle as Integer
440
∗ 16.1.10 Lasterror as Integer
440
∗ 16.1.11 ItemHidden as boolean
440
∗ 16.1.12 LoginItemHidden as boolean
440
∗ 16.1.14 kDoNotMountVolumes = 2
441
∗ 16.1.15 kNoUserInteraction = 1
441
– 16.2.1 class LSSharedFileListMBS
442
∗ 16.2.3 Constructor(type as Integer)
442
∗ 16.2.4 GetSeedValue as UInt32
442
∗ 16.2.5 InsertFile(AfterItem as LSSharedFileListItemMBS, DisplayName as string, Icon as
object, file as folderitem) as LSSharedFileListItemMBS
442
∗ 16.2.6 InsertURL(AfterItem as LSSharedFileListItemMBS, DisplayName as string, Icon as
object, URL as string) as LSSharedFileListItemMBS
443
∗ 16.2.7 kLSSharedFileListItemBeforeFirst as LSSharedFileListItemMBS
444
∗ 16.2.8 kLSSharedFileListItemLast as LSSharedFileListItemMBS
444
∗ 16.2.9 Move(item as LSSharedFileListItemMBS, MoveAfterItem as LSSharedFileListItemMBS)
444
∗ 16.2.10 Remove(item as LSSharedFileListItemMBS)
444
∗ 16.2.11 RemoveAllItems
445
∗ 16.2.12 SetAuthorization(handle as Integer)
445
∗ 16.2.13 Snapshot as LSSharedFileListItemMBS()
445
∗ 16.2.14 Snapshot(byref seed as UInt32) as LSSharedFileListItemMBS()
446
∗ 16.2.16 Handle as Integer
446
∗ 16.2.17 Lasterror as Integer
446
∗ 16.2.18 RecentItemsMaxAmount as Integer
446
∗ 16.2.19 VolumesComputerVisible as boolean
446
∗ 16.2.20 VolumesIDiskVisible as boolean
446
∗ 16.2.21 VolumesNetworkVisible as boolean
447
∗ 16.2.23 Changed
447
∗ 16.2.25 kFavoriteItems = 2
447
∗ 16.2.26 kFavoriteVolumes = 1
448
∗ 16.2.27 kGlobalLoginItems = 7
448
∗ 16.2.28 kRecentApplicationItems = 3
449
∗ 16.2.29 kRecentDocumentItems = 4
449
∗ 16.2.30 kRecentServerItems = 5
450
∗ 16.2.31 kSessionLoginItems = 6
450
45
• 11 Files
191
– 11.2.1 class MacQuarantinePropertiesMBS
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
195
11.2.3 AgentBundleIdentifier as String
195
11.2.4 AgentName as String
196
11.2.5 DataURL as String
196
11.2.6 Dic as Variant
196
11.2.7 OriginURL as String
197
11.2.8 TimeStamp as Date
197
11.2.9 Type as String
198
11.2.11 kTypeCalendarEventAttachment = ”LSQuarantineTypeCalendarEventAttachment”
198
11.2.12 kTypeEmailAttachment = ”LSQuarantineTypeEmailAttachment”
198
11.2.13 kTypeInstantMessageAttachment = ”LSQuarantineTypeInstantMessageAttachment”
198
11.2.14 kTypeOtherAttachment = ”LSQuarantineTypeOtherAttachment”
198
11.2.15 kTypeOtherDownload = ”LSQuarantineTypeOtherDownload”
198
11.2.16 kTypeWebDownload = ”LSQuarantineTypeWebDownload”
199
46
CHAPTER 1. LIST OF TOPICS
• 17 Media Keys
– 17.1.1 class MediaKeysMBS
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
451
451
17.1.3 Constructor
452
17.1.4 Keys(keyCode as Integer) as Integer
452
17.1.5 startWatchingMediaKeys
452
17.1.6 stopWatchingMediaKeys
452
17.1.8 receivedMediaKeyEvent(e as NSEventMBS, keyCode as Integer, keyFlags as Integer,
keyState as Integer, keyRepeat as Integer)
453
17.1.10 kMediaKeyBrightnessDown = 3
453
17.1.11 kMediaKeyBrightnessUp = 2
454
17.1.12 kMediaKeyCapsLock = 4
454
17.1.13 kMediaKeyContrastDown = 12
454
17.1.14 kMediaKeyContrastUp = 11
454
17.1.15 kMediaKeyDownArrow = 9
455
17.1.16 kMediaKeyEject = 14
455
17.1.17 kMediaKeyFast = 19
455
17.1.18 kMediaKeyHelp = 5
456
17.1.19 kMediaKeyIlluminationDown = 22
456
17.1.20 kMediaKeyIlluminationToggle = 23
456
17.1.21 kMediaKeyIlluminationUp = 21
456
17.1.22 kMediaKeyLaunchPanel = 13
457
17.1.23 kMediaKeyMute = 7
457
17.1.24 kMediaKeyNext = 17
457
17.1.25 kMediaKeyNumLock = 10
458
17.1.26 kMediaKeyPlay = 16
458
17.1.27 kMediaKeyPower = 6
458
17.1.28 kMediaKeyPrevious = 18
459
17.1.29 kMediaKeyRewind = 20
459
17.1.30 kMediaKeySoundDown = 1
459
17.1.31 kMediaKeySoundUp = 0
460
17.1.32 kMediaKeyUpArrow = 8
460
17.1.33 kMediaKeyVideoMirror = 15
460
17.1.34 kModeBlock = 1
460
17.1.35 kModeEventAndBlock = 2
461
17.1.36 kModeEventAndPass = 3
461
17.1.37 kModePass = 0
461
47
• 6 Cocoa
119
– 6.3.1 class NSAnimationContextMBS
∗
∗
∗
∗
∗
∗
6.3.3
6.3.4
6.3.5
6.3.6
6.3.8
6.3.9
beginGrouping
Constructor
currentContext as NSAnimationContextMBS
endGrouping
Handle as Integer
duration as Double
– 6.4.1 class NSAnimationMBS
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
6.4.3 clearStartAnimation
6.4.4 clearStopAnimation
6.4.5 Constructor(duration as Double, animationCurve as Integer)
6.4.6 currentValue as Double
6.4.7 Destructor
6.4.8 isAnimating as boolean
6.4.9 startAnimation
6.4.10 stopAnimation
6.4.12 Handle as Integer
6.4.13 animationBlockingMode as Integer
6.4.14 animationCurve as Integer
6.4.15 currentProgress as Double
6.4.16 duration as Double
6.4.17 frameRate as Double
6.4.19 CurrentProgressChanged(progress as Double)
6.4.21 NSAnimationBlocking=0
6.4.22 NSAnimationEaseIn=1
6.4.23 NSAnimationEaseInOut=0
6.4.24 NSAnimationEaseOut=2
6.4.25 NSAnimationLinear=3
6.4.26 NSAnimationNonblocking=1
6.4.27 NSAnimationNonblockingThreaded=2
126
126
126
126
126
127
127
128
128
128
128
129
129
129
129
129
130
130
130
130
131
131
131
131
132
132
132
132
132
132
48
CHAPTER 1. LIST OF TOPICS
• 8 Cocoa Threading
– 8.1.1 class NSOperationMBS
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
∗
8.1.3 addDependency(op as NSOperationMBS)
8.1.4 cancel
8.1.5 Constructor
8.1.6 Constructor(Handle as Integer)
8.1.7 dependencies as NSOperationMBS()
8.1.8 dependenciesCount as Integer
8.1.9 dependency(index as Integer) as NSOperationMBS
8.1.10 isCancelled as boolean
8.1.11 isConcurrent as boolean
8.1.12 isExecuting as boolean
8.1.13 isFinished as boolean
8.1.14 isReady as boolean
8.1.15 Lock
8.1.16 main
8.1.17 removeDependency(op as NSOperationMBS)
8.1.18 start
8.1.19 Unlock
8.1.20 waitUntilFinished
8.1.22 Handle as Integer
8.1.23 queuePriority as Integer
8.1.24 threadPriority as Double
8.1.26 Close
8.1.27 Finished
8.1.28 Open
8.1.29 Work
8.1.31 NSOperationQueuePriorityHigh=4
8.1.32 NSOperationQueuePriorityLow=-4
8.1.33 NSOperationQueuePriorityNormal=0
8.1.34 NSOperationQueuePriorityVeryHigh=8
8.1.35 NSOperationQueuePriorityVeryLow=-8
– 8.2.1 class NSOperationQueueMBS
∗
∗
∗
∗
∗
∗
∗
∗
8.2.3 addOperation(op as NSOperationMBS)
8.2.4 addOperations(ops() as NSOperationMBS, wait as boolean)
8.2.5 areAllOperationsFinished as boolean
8.2.6 cancelAllOperations
8.2.7 Constructor
8.2.8 currentQueue as NSOperationQueueMBS
8.2.9 isOneOperationExecuting as boolean
8.2.10 mainQueue as NSOperationQueueMBS
139
139
140
140
140
141
141
141
141
141
142
142
142
142
143
143
143
144
144
144
145
145
145
146
146
146
146
146
147
147
147
147
148
148
149
149
149
150
150
150
150
49
∗
∗
∗
∗
∗
∗
∗
∗
∗
8.2.11
8.2.12
8.2.13
8.2.14
8.2.16
8.2.17
8.2.18
8.2.19
8.2.21
operation(index as UInt32) as NSOperationMBS
operationCount as Integer
operations as NSOperationMBS()
waitUntilAllOperationsAreFinished
Handle as Integer
isSuspended as boolean
maxConcurrentOperationCount as Integer
name as string
NSOperationQueueDefaultMaxConcurrentOperationCount=-1
151
151
151
151
152
152
152
152
153
50
CHAPTER 1. LIST OF TOPICS
• 6 Cocoa
119
– 6.5.1 control WebViewControlMBS
∗
∗
∗
∗
∗
∗
∗
∗
∗
6.5.3 Available as Boolean
6.5.4 View as WebViewMBS
6.5.5 WantsFocus as Boolean
6.5.7 EnableMenuItems
6.5.8 MenuAction(HitItem as MenuItem) As Boolean
6.5.9 MouseDown(x as Integer, y as Integer, Modifiers as Integer) As Boolean
6.5.10 MouseDrag(x as Integer, y as Integer)
6.5.11 MouseUp(x as Integer, y as Integer)
6.5.12 ScaleFactorChanged(NewFactor as Double)
134
134
134
134
135
135
135
135
136
136
Chapter 2
List of all classes
• CalAlarmMBS
59
• CalAttendeeMBS
64
• CALayerMBS
155
• CalCalendarItemMBS
66
• CalCalendarMBS
72
• CalCalendarStoreMBS
77
• CalEventMBS
96
• CalNthWeekDayMBS
102
• CalRecurrenceEndMBS
103
• CalRecurrenceRuleMBS
105
• CalTaskMBS
115
• CATransactionMBS
175
• Control
137
• Folderitem
191
• FSEventsMBS
201
• ICCameraDeviceMBS
221
• ICCameraFileMBS
229
• ICCameraFolderMBS
231
• ICCameraItemMBS
232
51
52
CHAPTER 2. LIST OF ALL CLASSES
• ICDeviceBrowserMBS
237
• ICDeviceMBS
241
• ICScannerBandDataMBS
255
• ICScannerDeviceMBS
258
• ICScannerFeatureBooleanMBS
262
• ICScannerFeatureEnumerationMBS
263
• ICScannerFeatureMBS
265
• ICScannerFeatureRangeMBS
268
• ICScannerFeatureTemplateMBS
270
• ICScannerFunctionalUnitDocumentFeederMBS
271
• ICScannerFunctionalUnitFlatbedMBS
274
• ICScannerFunctionalUnitMBS
275
• ICScannerFunctionalUnitNegativeTransparencyMBS
298
• ICScannerFunctionalUnitPositiveTransparencyMBS
299
• IKCameraDeviceViewMBS
303
• IKDeviceBrowserViewMBS
313
• IKImageBrowserCellMBS
341
• IKImageBrowserItemMBS
347
• IKImageBrowserViewMBS
362
• IKImageEditPanelMBS
388
• IKPictureTakerMBS
391
• IKScannerDeviceViewMBS
320
• IKSlideshowMBS
399
• ImageCaptureEventsMBS
326
• JSClassMBS
407
• JSContextMBS
409
• JSObjectMBS
419
• JSValueMBS
425
• LSSharedFileListItemMBS
437
53
• LSSharedFileListMBS
442
• MacQuarantinePropertiesMBS
195
• MediaKeysMBS
451
• NSAnimationContextMBS
126
• NSAnimationMBS
128
• NSOperationMBS
139
• NSOperationQueueMBS
148
54
CHAPTER 2. LIST OF ALL CLASSES
Chapter 3
List of all controls
• CocoaControlMBS
119
• IKCameraDeviceViewControlMBS
300
• IKDeviceBrowserViewControlMBS
310
• IKImageBrowserViewControlMBS
351
• IKScannerDeviceViewControlMBS
317
• WebViewControlMBS
134
55
56
CHAPTER 3. LIST OF ALL CONTROLS
Chapter 4
List of all modules
• CGWindowMBS
179
• DictionaryServiceMBS
123
57
58
CHAPTER 4. LIST OF ALL MODULES
Chapter 5
Calendar
5.1
5.1.1
class CalAlarmMBS
class CalAlarmMBS
Plugin Version: 7.7, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: The class for an
Alarm in iCal.
Example:
// start a connection to the calendar database
dim s as new CalCalendarStoreMBS
// needed for the error details
dim e as NSErrorMBS
// create a new calendar
dim c as new CalEventMBS
dim StartDate as date = new date
StartDate.day = StartDate.day +1 // start tomorrow
dim calendars() as CalCalendarMBS = s.calendars
// set properties
c.Title=”new Event”
c.startDate=StartDate
c.calendar=calendars(0) // add to first calendar
dim EndDate as new date(StartDate) // one hour after start
EndDate.hour = EndDate.hour + 1
c.endDate=EndDate
59
60
CHAPTER 5. CALENDAR
dim a as new CalAlarmMBS // Send email one hour earlier
a.action = a.CalAlarmActionEmail
a.relativeTrigger = -3600
a.emailAddress=”[email protected]”
c.addAlarm a // attach an alarm
// save event
call s.saveEvent(c,s.CalSpanAllEvents, e)
if e<>nil then
MsgBox e.localizedDescription
else
MsgBox ”New event was created.”
end if
Notes: Requires Mac OS X 10.5 to work.
5.1.2
Methods
5.1.3
Constructor
Plugin Version: 7.7, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: This constructor
creates a new empty alarm object.
Example:
dim a as new CalAlarmMBS // add alarm
a.action = a.CalAlarmActionDisplay
a.relativeTrigger = -3600*24 // 24 Hours before
5.1.4
triggerDateRelativeTo(currentdate as date) as date
Plugin Version: 7.7, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: Returns the date of
the trigger relative to the given date.
5.1. CLASS CALALARMMBS
5.1.5
Properties
5.1.6
absoluteTrigger as date
61
Plugin Version: 7.7, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: The absolute trigger
value.
Notes:
The time that an alarm goes off is referred to as the trigger. Alarms have either a relative trigger, which
means the alarm fires a certain number of seconds before an alarm occurs, or an absolute trigger, which
specifies the exact time the alarm will trigger off.
Setting an absoluteTrigger will also set the relativeTrigger to 0.
(Read and Write property)
5.1.7
acknowledged as date
Plugin Version: 12.3, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: The acknowledged
date for the alarm.
Notes: (Read and Write property)
5.1.8
action as String
Plugin Version: 7.7, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: The action used for
this alarm.
Notes:
See the CalAlarmAction* constants.
(Read and Write property)
5.1.9
emailAddress as String
Plugin Version: 7.7, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: The email address
to notify.
Notes:
Setting an emailAddress will also set the action to CalAlarmEmail as well as set the sound and URL to nil.
(Read and Write property)
62
5.1.10
CHAPTER 5. CALENDAR
relatedTo as String
Plugin Version: 12.3, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: Related to text.
Notes: (Read and Write property)
5.1.11
relativeTrigger as Double
Plugin Version: 7.7, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: The absolute relative
value.
Notes:
The time that an alarm goes off is referred to as the trigger. Alarms have either a relative trigger, which
means the alarm fires a certain number of seconds before an alarm occurs, or an absolute trigger, which
specifies the exact time the alarm will trigger off.
Setting a relativeTrigger will also set the absoluteTrigger to 0.
(Read and Write property)
5.1.12
sound as String
Plugin Version: 7.7, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: The sound file to
play.
Notes:
Setting a sound will also set the action to CalAlarmSound as well as set the emailAddress and URL to nil.
Expects the name of a system alert. See NSSound.
(Read and Write property)
5.1.13
url as string
Plugin Version: 7.7, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: The URL to launch
when the alarm comes.
Notes:
Setting a URL will also set the action to CalAlarmProcedure as well as set the emailAddress and sound to
nil. The URL must be a file URL.
(Read and Write property)
5.1. CLASS CALALARMMBS
5.1.14
Constants
5.1.15
CalAlarmActionDisplay=”DISPLAY”
Plugin Version: 7.7. Function: One of the alarm action constants.
Notes: Display the event.
5.1.16
CalAlarmActionEmail=”EMAIL”
Plugin Version: 7.7. Function: One of the alarm action constants.
Notes: Send an email.
5.1.17
CalAlarmActionProcedure=”PROCEDURE”
Plugin Version: 7.7. Function: One of the alarm action constants.
5.1.18
CalAlarmActionSound=”AUDIO”
Plugin Version: 7.7. Function: One of the alarm action constants.
Notes: Play a sound.
63
64
5.2
5.2.1
CHAPTER 5. CALENDAR
class CalAttendeeMBS
class CalAttendeeMBS
Plugin Version: 7.7, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: The class for an
Attendee.
Notes:
Requires Mac OS X 10.5 to work.
This is an abstract class. You can’t create an instance, but you can get one from various plugin functions.
5.2.2
Methods
5.2.3
Constructor
Plugin Version: 13.1, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: The private constructor.
5.2.4
Properties
5.2.5
address as String
Plugin Version: 7.7, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: The address of this
attendee.
Notes: (Read only property)
5.2.6
commonName as String
Plugin Version: 7.7, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: The user-entered
name of the attendee.
Notes: (Read only property)
5.2.7
Handle as Integer
Plugin Version: 7.7, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: The internal used
CalAttendee reference.
Notes: (Read and Write property)
5.2. CLASS CALATTENDEEMBS
5.2.8
65
status as String
Plugin Version: 7.7, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: The attendee status.
Notes:
Use the CalAttendeeStatus* constants.
For now (Mac OS X 10.5), it is not possible to modify an event’s attendees or the attendees themselves.
(Read only property)
5.2.9
5.2.10
Constants
CalAttendeeStatusAccepted=”ACCEPTED”
Plugin Version: 7.7. Function: These constants are used to describe the user’s confirmation status for an
attendee.
5.2.11
CalAttendeeStatusDeclined=”DECLINED”
Plugin Version: 7.7. Function: These constants are used to describe the user’s confirmation status for an
attendee.
5.2.12
CalAttendeeStatusNeedsAction=”NEEDS-ACTION”
Plugin Version: 7.7. Function: These constants are used to describe the user’s confirmation status for an
attendee.
Notes: This is the default status for an attendee.
5.2.13
CalAttendeeStatusTentative=”TENTATIVE”
Plugin Version: 7.7. Function: These constants are used to describe the user’s confirmation status for an
attendee.
66
5.3
5.3.1
CHAPTER 5. CALENDAR
class CalCalendarItemMBS
class CalCalendarItemMBS
Plugin Version: 7.7, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: The class for a
calendar item in iCal.
Notes:
This class and its subclasses should be used to get information about CalEvent and CalTasks. Accessors for
properties common to both of these classes are included here.
Requires Mac OS X 10.5 to work.
This is an abstract class. You can’t create an instance, but you can get one from various plugin functions.
5.3.2
Methods
5.3.3
addAlarm(alarm as CalAlarmMBS)
Plugin Version: 7.7, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: Adds one alarm.
5.3.4
addAlarms(alarms() as CalAlarmMBS)
Plugin Version: 7.7, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: Adds an array of
alarms.
5.3.5
alarms as CalAlarmMBS()
Plugin Version: 11.2, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: An array of
CalAlarms associated with the calendar item.
5.3.6
Constructor
Plugin Version: 13.1, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: The private constructor.
5.3. CLASS CALCALENDARITEMMBS
5.3.7
67
hasAlarm as Boolean
Plugin Version: 7.7, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: Whether this item
has an alarm associated.
5.3.8
nextAlarmDate as date
Plugin Version: 7.7, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: Returns the next
alaram date.
5.3.9
removeAlarm(alarm as CalAlarmMBS)
Plugin Version: 7.7, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: Removes one alarm.
5.3.10
removeAlarms(alarms() as CalAlarmMBS)
Plugin Version: 7.7, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: Removes the alarms.
5.3.11
setalarms(alarms() as CalAlarmMBS)
Plugin Version: 7.7, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: Sets the alarms for
this item.
5.3.12
Show
Plugin Version: 12.2, Console & Web: Yes, Mac: Yes, Win: Yes, Linux: Yes. Function: Shows the item in
iCal.
Example:
dim c as new CalCalendarStoreMBS
// search for some events within last year
dim d as new date
dim e as new date
d.Year = d.Year -1
dim events() as CalEventMBS = c.events(d, e)
68
CHAPTER 5. CALENDAR
// pick one, show title and show in iCal
MsgBox Events(30).Title
events(30).show
5.3.13
Properties
5.3.14
calendar as CalCalendarMBS
Plugin Version: 7.7, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: The calendar of this
item.
Notes: (Read and Write property)
5.3.15
dateStamp as date
Plugin Version: 7.7, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: The datestamp of
this calendar item.
Notes:
This value is read only.
(Read only property)
5.3.16
Handle as Integer
Plugin Version: 7.7, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: The internal used
CalCalendarItem reference.
Notes: (Read and Write property)
5.3.17
notes as String
Plugin Version: 7.7, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: The notes text for
this item.
Example:
dim c as new CalCalendarStoreMBS
// set the date range where we look for event
dim sd as new date(2016,6,7,0,0,0)
dim ed as new date(2016,6,7,23,59,59)
5.3. CLASS CALCALENDARITEMMBS
69
// look for an event on that date
dim a() as CalEventMBS = c.events(sd,ed, c.calendars)
dim e as CalEventMBS = a(1)
// show notes
MsgBox e.notes
// change it
e.notes = ”Just a test”
// check again
MsgBox e.notes
// Save
dim error as NSErrorMBS
dim ok as Boolean = c.saveEvent(e, c.CalSpanThisEvent, error)
if ok then
MsgBox ”OK”
elseif error <>nil then
MsgBox error.LocalizedDescription
else
MsgBox ”Failed.”
end if
Notes: (Read and Write property)
5.3.18
title as String
Plugin Version: 7.7, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: The title for this
calendar item.
Example:
// init
dim s as new CalCalendarStoreMBS
// Get date range for today
dim Startdate as new date
dim Enddate as new date
Startdate.hour = 0
Startdate.Minute = 0
Startdate.Second = 0
70
CHAPTER 5. CALENDAR
Enddate.hour = 23
Enddate.minute = 59
Enddate.second = 59
// Query events on all calendars
dim events() as CalEventMBS = s.events(Startdate,Enddate)
// Display result
dim lines(-1) as string
for each e as CalEventMBS in events
lines.Append e.Title
next
MsgBox Join(lines,EndOfLine)
Notes: (Read and Write property)
5.3.19
uid as String
Plugin Version: 7.7, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: The unique ID for
this item.
Example:
// start a connection to the calendar database
dim s as new CalCalendarStoreMBS
// needed for the error details
dim e as NSErrorMBS
// create a new calendar event
dim c as new CalEventMBS
dim calendars() as CalCalendarMBS = s.calendars
// set properties
c.Title=”new Event”
c.startDate=new date
c.calendar=calendars(0) // add to first calendar
dim d as new date
d.hour=d.hour+1
c.endDate=d
// save event
call s.saveEvent(c,s.CalSpanAllEvents, e)
5.3. CLASS CALCALENDARITEMMBS
71
if e<>nil then
MsgBox e.localizedDescription
else
// show the UID
MsgBox ”New event was created with UID: ”+c.uid
end if
Notes:
This value is read only.
(Read only property)
5.3.20
URL as String
Plugin Version: 7.7, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: The URL for this
calendar item.
Notes: (Read and Write property)
72
5.4
5.4.1
CHAPTER 5. CALENDAR
class CalCalendarMBS
class CalCalendarMBS
Plugin Version: 7.7, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: A class for the iCal
calendars.
Example:
// start a connection to the calendar database
dim s as new CalCalendarStoreMBS
// needed for the error details
dim e as NSErrorMBS
// create a new calendar
dim c as new CalCalendarMBS
// set properties
c.Title=”New Calendar”
c.notes=”Just a test”
// save calendar
call s.saveCalendar(c,e)
if e<>nil then
MsgBox e.localizedDescription
else
MsgBox ”New calendar was created.”
end if
Notes:
Requires Mac OS X 10.5 to work.
This class can be used to get attributes of a calendar, but cannot be used to get the list of events or tasks
in a calendar.
5.4.2
Methods
5.4.3
Constructor
Plugin Version: 7.7, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: The iCal class for a
calendar.
Example:
5.4. CLASS CALCALENDARMBS
73
// start a connection to the calendar database
dim s as new CalCalendarStoreMBS
// needed for the error details
dim e as NSErrorMBS
// create a new calendar
dim c as new CalCalendarMBS
// set properties
c.Title=”New Calendar”
c.notes=”Just a test”
// save calendar
call s.saveCalendar(c,e)
if e<>nil then
MsgBox e.localizedDescription
else
MsgBox ”New calendar was created.”
end if
Notes: All calendars created with this API will be of type CalCalendarTypeLocal.
5.4.4
Properties
5.4.5
Color as NSColorMBS
Plugin Version: 13.2, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: The color for this
calendar.
Notes: (Read and Write property)
5.4.6
Handle as Integer
Plugin Version: 13.2, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: The internal object
reference.
Notes: (Read and Write property)
74
5.4.7
CHAPTER 5. CALENDAR
isEditable as Boolean
Plugin Version: 7.7, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: Whether this calendar
is editable.
Notes:
This property is read only.
(Read only property)
5.4.8
notes as String
Plugin Version: 7.7, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: The notes for this
calendar.
Notes: (Read and Write property)
5.4.9
title as String
Plugin Version: 7.7, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: The title of this
calendar.
Example:
dim c as new CalCalendarStoreMBS
dim ca() as CalCalendarMBS = c.calendars
for each cc as CalCalendarMBS in ca
MsgBox cc.Title+EndOfLine+cc.type+EndOfLine+cc.notes
next
Notes: (Read and Write property)
5.4.10
type as String
Plugin Version: 7.7, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: The type of this
calendar.
Notes:
This property is read only.
use the CalCalendarType* constants.
(Read only property)
5.4. CLASS CALCALENDARMBS
5.4.11
75
uid as String
Plugin Version: 7.7, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: The unique ID for
this calendar.
Notes:
This property is read only.
(Read only property)
5.4.12
Constants
5.4.13
CalCalendarTypeBirthday=”Birthday”
Plugin Version: 7.7. Function: One of the calendar types.
Example:
// searches for the birthday calendar and than lists all birthdays in the next month
dim
dim
dim
dim
dim
dim
dim
cals(-1) as CalCalendarMBS
a() as CalCalendarMBS
i as Integer
cal as CalCalendarMBS
sd,ed as date
ea() as CalEventMBS
e as CalEventMBS
dim c as new CalCalendarStoreMBS
a=c.calendars
for each cal in a
MsgBox ”Calendar: ”+cal.Title
if cal.type=cal.CalCalendarTypeBirthday then
cals.Append cal
end if
next
sd=new date
ed=new date
ed.Month=sd.Month+1
ea=c.events(sd,ed,cals)
for each e in ea
MsgBox ”Event: ”+e.Title
next
76
5.4.14
CHAPTER 5. CALENDAR
CalCalendarTypeCalDAV=”CalDAV”
Plugin Version: 7.7. Function: One of the calendar types.
5.4.15
CalCalendarTypeExchange=”Exchange”
Plugin Version: 9.6. Function: One of the calendar types.
Notes: New in Mac OS X 10.6.
5.4.16
CalCalendarTypeIMAP=”IMAP”
Plugin Version: 7.7. Function: One of the calendar types.
5.4.17
CalCalendarTypeLocal=”Local”
Plugin Version: 7.7. Function: One of the calendar types.
5.4.18
CalCalendarTypeSubscription=”Subscription”
Plugin Version: 7.7. Function: One of the calendar types.
5.5. CLASS CALCALENDARSTOREMBS
5.5
5.5.1
77
class CalCalendarStoreMBS
class CalCalendarStoreMBS
Plugin Version: 7.7, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: The class for the
calendar storage.
Example:
// init
dim s as new CalCalendarStoreMBS
// find calendar by name
dim myCalendar as CalCalendarMBS
dim calendars() as CalCalendarMBS = s.calendars
for each ca as CalCalendarMBS in calendars
if ca.Title = ”Private Events” then
myCalendar=ca
exit
end if
next
// Get date range for today
dim Startdate as new date
dim Enddate as new date
Startdate.hour = 0
Startdate.Minute = 0
Startdate.Second = 0
Enddate.hour = 23
Enddate.minute = 59
Enddate.second = 59
// Query events on this calendar
dim events() as CalEventMBS = s.events(Startdate,Enddate, myCalendar)
// Display result
dim lines(-1) as string
for each e as CalEventMBS in events
lines.Append e.Title
next
MsgBox Join(lines,EndOfLine)
Notes:
78
CHAPTER 5. CALENDAR
Requires Mac OS X 10.5 to work.
Calendar saving and modification errors:
CalCalendarNotEditableError
CalDateInvalidError
CalCalendarNotInRepository
CalCalendarTitleNotUniqueError
= 1025
= 1026
= 1027
= 1028
Events and tasks cannot be added to an uneditable calendar
The start date of an event must be earlier than its end date
Events’ and tasks’ calendar property must be a calendar in the user’s calendar
store
Calendar titles must be unique
And the domain for the errors is: CalCalendarStoreErrorDomain
5.5.2
Methods
5.5.3
calendars as CalCalendarMBS()
Plugin Version: 11.2, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: An array of all the
user’s calendars, represented as CalCalendars.
Example:
dim c as new CalCalendarStoreMBS
dim ca() as CalCalendarMBS
ca=c.calendars
for each cc as CalCalendarMBS in ca
MsgBox cc.Title+EndOfLine+cc.type+EndOfLine+cc.notes
next
Notes:
If the user has iCal data from a previous version of Mac OS X, but has not launched iCal in 10.5, this will
return an array of empty calendars. iCal needs to be launched at least once in order to migrate the user’s
calendar data.
If no calendar data from any version of Mac OS X exists, then this method will create and return two default
calendars, named Home and Work.
5.5.4
calendarWithTitle(Title as string) as CalCalendarMBS
Plugin Version: 14.2, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: Queries all calendars
and searches for one with the given title.
5.5. CLASS CALCALENDARSTOREMBS
79
Example:
dim cs as new CalCalendarStoreMBS
// delete one
dim c as CalCalendarMBS = cs.calendarWithTitle(”Just Testing”)
dim e as NSErrorMBS
if cs.removeCalendar(c, e) then
MsgBox ”deleted”
else
MsgBox ”Failed to remove: ”+e.LocalizedDescription
end if
Notes:
Title comparison is case insensitive.
Returns nil on any error.
5.5.5
calendarWithUID(UID as string) as CalCalendarMBS
Plugin Version: 7.7, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: The calendar associated with the specific UID.
Notes: If no record with this UID exists, nil is returned.
5.5.6
Constructor
Plugin Version: 7.7, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: The class for the
calendar storage.
Notes: This is the main class. Keep an object of it around as long as you use the calendar classes.
5.5.7
events(StartDate as date, EndDate as date) as CalEventMBS()
Plugin Version: 11.2, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: This method returns
an array of all the CalEvents which match the condition.
Example:
dim c as new CalCalendarStoreMBS
dim i,count as Integer
dim ta() as CalEventMBS
dim ct as CalEventMBS
80
CHAPTER 5. CALENDAR
dim sd as new date
dim ed as new date
ed.day=ed.day+1
// events within the next 24 hours
ta=c.events(sd,ed)
for each ct in ta
msgbox ct.Title+EndOfLine+ct.location+EndOfLine+ct.startDate.LongDate+” ”+ct.startDate.LongTime
next
Notes:
This is the function which uses all calendars.
For performance reasons, this method will only return occurrences of repeating events that fall within a
specific four year timespan. If the date range between the startDate and endDate is greater than four years,
then the timespan containing recurrences is always the first four years of date range.
See also:
• 5.5.8 events(StartDate as date, EndDate as date, calendar as CalCalendarMBS) as CalEventMBS() 80
• 5.5.9 events(StartDate as date, EndDate as date, calendars() as CalCalendarMBS) as CalEventMBS()
82
• 5.5.10 events(StartDate as date, EndDate as date, eventUID as string) as CalEventMBS()
82
• 5.5.11 events(StartDate as date, EndDate as date, eventUID as string, calendar as CalCalendarMBS)
as CalEventMBS()
83
• 5.5.12 events(StartDate as date, EndDate as date, eventUID as string, calendars() as CalCalendarMBS)
as CalEventMBS()
83
5.5.8
events(StartDate as date, EndDate as date, calendar as CalCalendarMBS)
as CalEventMBS()
Plugin Version: 11.2, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: This method returns
an array of all the CalEvents which match the condition.
Example:
// init
dim s as new CalCalendarStoreMBS
// find calendar by name
dim myCalendar as CalCalendarMBS
dim calendars() as CalCalendarMBS = s.calendars
5.5. CLASS CALCALENDARSTOREMBS
81
for each ca as CalCalendarMBS in calendars
if ca.Title = ”Private Events” then
myCalendar=ca
exit
end if
next
// Get date range for today
dim Startdate as new date
dim Enddate as new date
Startdate.hour = 0
Startdate.Minute = 0
Startdate.Second = 0
Enddate.hour = 23
Enddate.minute = 59
Enddate.second = 59
// Query events on this calendar
dim events() as CalEventMBS = s.events(Startdate,Enddate, myCalendar)
// Display result
dim lines(-1) as string
for each e as CalEventMBS in events
lines.Append e.Title
next
MsgBox Join(lines,EndOfLine)
Notes: For performance reasons, this method will only return occurrences of repeating events that fall
within a specific four year timespan. If the date range between the startDate and endDate is greater than
four years, then the timespan containing recurrences is always the first four years of date range.
See also:
• 5.5.7 events(StartDate as date, EndDate as date) as CalEventMBS()
79
• 5.5.9 events(StartDate as date, EndDate as date, calendars() as CalCalendarMBS) as CalEventMBS()
82
• 5.5.10 events(StartDate as date, EndDate as date, eventUID as string) as CalEventMBS()
82
• 5.5.11 events(StartDate as date, EndDate as date, eventUID as string, calendar as CalCalendarMBS)
as CalEventMBS()
83
• 5.5.12 events(StartDate as date, EndDate as date, eventUID as string, calendars() as CalCalendarMBS)
as CalEventMBS()
83
82
CHAPTER 5. CALENDAR
5.5.9
events(StartDate as date, EndDate as date, calendars() as CalCalendarMBS) as CalEventMBS()
Plugin Version: 11.2, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: This method returns
an array of all the CalEvents which match the condition.
Notes: For performance reasons, this method will only return occurrences of repeating events that fall
within a specific four year timespan. If the date range between the startDate and endDate is greater than
four years, then the timespan containing recurrences is always the first four years of date range.
See also:
• 5.5.7 events(StartDate as date, EndDate as date) as CalEventMBS()
79
• 5.5.8 events(StartDate as date, EndDate as date, calendar as CalCalendarMBS) as CalEventMBS() 80
• 5.5.10 events(StartDate as date, EndDate as date, eventUID as string) as CalEventMBS()
82
• 5.5.11 events(StartDate as date, EndDate as date, eventUID as string, calendar as CalCalendarMBS)
as CalEventMBS()
83
• 5.5.12 events(StartDate as date, EndDate as date, eventUID as string, calendars() as CalCalendarMBS)
as CalEventMBS()
83
5.5.10
events(StartDate as date, EndDate as date, eventUID as string) as
CalEventMBS()
Plugin Version: 11.2, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: This method returns
an array of all the CalEvents which match the condition.
Notes:
This is the function which uses all calendars.
For performance reasons, this method will only return occurrences of repeating events that fall within a
specific four year timespan. If the date range between the startDate and endDate is greater than four years,
then the timespan containing recurrences is always the first four years of date range.
See also:
• 5.5.7 events(StartDate as date, EndDate as date) as CalEventMBS()
79
• 5.5.8 events(StartDate as date, EndDate as date, calendar as CalCalendarMBS) as CalEventMBS() 80
• 5.5.9 events(StartDate as date, EndDate as date, calendars() as CalCalendarMBS) as CalEventMBS()
82
• 5.5.11 events(StartDate as date, EndDate as date, eventUID as string, calendar as CalCalendarMBS)
as CalEventMBS()
83
• 5.5.12 events(StartDate as date, EndDate as date, eventUID as string, calendars() as CalCalendarMBS)
as CalEventMBS()
83
5.5. CLASS CALCALENDARSTOREMBS
5.5.11
83
events(StartDate as date, EndDate as date, eventUID as string, calendar
as CalCalendarMBS) as CalEventMBS()
Plugin Version: 11.2, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: This method returns
an array of all the CalEvents which match the condition.
Notes: For performance reasons, this method will only return occurrences of repeating events that fall
within a specific four year timespan. If the date range between the startDate and endDate is greater than
four years, then the timespan containing recurrences is always the first four years of date range.
See also:
• 5.5.7 events(StartDate as date, EndDate as date) as CalEventMBS()
79
• 5.5.8 events(StartDate as date, EndDate as date, calendar as CalCalendarMBS) as CalEventMBS() 80
• 5.5.9 events(StartDate as date, EndDate as date, calendars() as CalCalendarMBS) as CalEventMBS()
82
• 5.5.10 events(StartDate as date, EndDate as date, eventUID as string) as CalEventMBS()
82
• 5.5.12 events(StartDate as date, EndDate as date, eventUID as string, calendars() as CalCalendarMBS)
as CalEventMBS()
83
5.5.12
events(StartDate as date, EndDate as date, eventUID as string, calendars() as CalCalendarMBS) as CalEventMBS()
Plugin Version: 11.2, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: This method returns
an array of all the CalEvents which match the condition.
Notes: For performance reasons, this method will only return occurrences of repeating events that fall
within a specific four year timespan. If the date range between the startDate and endDate is greater than
four years, then the timespan containing recurrences is always the first four years of date range.
See also:
• 5.5.7 events(StartDate as date, EndDate as date) as CalEventMBS()
79
• 5.5.8 events(StartDate as date, EndDate as date, calendar as CalCalendarMBS) as CalEventMBS() 80
• 5.5.9 events(StartDate as date, EndDate as date, calendars() as CalCalendarMBS) as CalEventMBS()
82
• 5.5.10 events(StartDate as date, EndDate as date, eventUID as string) as CalEventMBS()
82
• 5.5.11 events(StartDate as date, EndDate as date, eventUID as string, calendar as CalCalendarMBS)
as CalEventMBS()
83
5.5.13
eventsMT(StartDate as date, EndDate as date, calendars() as CalCalendarMBS = nil) as CalEventMBS()
Plugin Version: 16.5, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: This method returns
an array of all the CalEvents which match the condition.
84
CHAPTER 5. CALENDAR
Notes:
For performance reasons, this method will only return occurrences of repeating events that fall within a
specific four year timespan. If the date range between the startDate and endDate is greater than four years,
then the timespan containing recurrences is always the first four years of date range.
If calendars array is nil, we use all calendars.
The work is performed on an extra thread, so this function can yield time to other Xojo (Real Studio)
threads. For best user experience run this command on a Xojo (Real Studio) thread, so your GUI stays
responsive.
5.5.14
eventWithUID(UID as string, occurrence as date) as CalEventMBS
Plugin Version: 7.7, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: Searches the event
with the given unique ID.
Example:
// connect to calendar storage
dim c as new CalCalendarStoreMBS
// find event with given UID
dim e as CalEventMBS = c.eventWithUID(”M2CD-6-1-EEB42862-8BD6-4880-AF91-4AEEADD900B6”, nil)
// and display title
MsgBox e.Title
Notes:
Returns nil on any error.
uid: The unique identifier of an event.
date: The date of a recurring event. Pass nil if the event is not recurring.
Returns a CalEvent object that matches the specified unique identifier and date. Returns nil if the event is
not found, or the event is recurring and date is not specified.
Available in Mac OS X v10.5 and later.
5.5. CLASS CALCALENDARSTOREMBS
5.5.15
85
removeCalendar(calendar as CalCalendarMBS, byref error as NSErrorMBS)
as boolean
Plugin Version: 7.7, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: Deletes a calendar.
Example:
dim cs as new CalCalendarStoreMBS
// before
dim calendars1() as CalCalendarMBS = cs.calendars
dim list1() as string
for each c1 as CalCalendarMBS in calendars1
list1.Append c1.Title
next
MsgBox Join(list1, EndOfLine)
// delete one
dim c as CalCalendarMBS = cs.calendarWithTitle(”Just Testing”)
dim e as NSErrorMBS
if cs.removeCalendar(c, e) then
MsgBox ”deleted”
else
MsgBox ”Failed to remove: ”+e.LocalizedDescription
end if
// after
dim calendars2() as CalCalendarMBS = cs.calendars
dim list2() as string
for each c2 as CalCalendarMBS in calendars2
list2.Append c2.Title
next
MsgBox Join(list2, EndOfLine)
Notes: Return
86
5.5.16
CHAPTER 5. CALENDAR
removeEvent(theEvent as CalEventMBS, span as Integer, byref error as
NSErrorMBS) as boolean
Plugin Version: 7.7, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: Removes the event
from the calendar.
Example:
// start a connection to the calendar database
dim s as new CalCalendarStoreMBS
// needed for the error details
dim e as NSErrorMBS
// create a new calendar event
dim c as new CalEventMBS
dim calendars() as CalCalendarMBS = s.calendars
// set properties
c.Title=”new Event”
c.startDate=new date
c.calendar=calendars(0) // add to first calendar
dim d as new date
d.hour=d.hour+1
c.endDate=d
// save event
call s.saveEvent(c,s.CalSpanAllEvents, e)
if e<>nil then
MsgBox e.localizedDescription
else
MsgBox ”New event was created with UID: ”+c.uid
e = nil
// and delete it
if s.removeEvent(c, s.CalSpanAllEvents, e) then
MsgBox ”Event deleted.”
else
MsgBox e.localizedDescription
end if
end if
Notes:
5.5. CLASS CALCALENDARSTOREMBS
87
Returns true on success and false on failure.
Error is stored in the error object.
5.5.17
removeTask(task as CalTaskMBS, byref error as NSErrorMBS) as boolean
Plugin Version: 7.7, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: Removes the task
from the calendar.
Notes:
Returns true on success and false on failure.
Error is stored in the error object.
5.5.18
saveCalendar(calendar as CalCalendarMBS, byref error as NSErrorMBS)
as boolean
Plugin Version: 7.7, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: Writes changes to
calendar.
Example:
dim cs as new CalCalendarStoreMBS
dim c as new CalCalendarMBS
c.Title = ”Just Testing”
dim e as NSErrorMBS
if cs.saveCalendar(c, e) then
MsgBox ”OK”
else
MsgBox ”Failed ”+e.LocalizedDescription
end if
Notes:
The saveCalendar and the removeCalendar calendars allow the client to add, modify, and remove calendars
in the user’s calendar store. saveCalendar should be used both to add a new calendar to the calendar store,
and to modify a calendar already in the store.
The only calendars that can be added with this API are local calendars; it is not possible to add subscribed
or CalDAV calendars, or the birthday calendar.
Changes made to a CalCalendar are not persisted until that calendar has been passed to saveCalendar. If
saveCalendar is not called, the changes will be lost.
88
CHAPTER 5. CALENDAR
5.5.19
saveEvent(theEvent as CalEventMBS, span as Integer, byref error as
NSErrorMBS) as boolean
Plugin Version: 7.7, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: This method allows
the client to add or modify events in the user’s calendar store.
Notes:
This method should be used both to add a new event to the calendar store, and to modify an event already
in the calendar store.
If the event being saved is a repeating event, the second argument is used to describe whether the change
being made should apply to future occurrences of that event, all occurrences, or only this instance. This is
analogous to options on the dialog iCal presents when a user modifies a recurring event (though iCal’s UI
does not provide a way to change all events, past and present).
Changes made to a CalEvent are not persisted until that event has been passed to saveEvent. If saveEvent
is not called, the changes will be lost.
Applying changes to all events or all future events may cause the UID or the occurrence date of the event
to change.
5.5.20
saveTask(task as CalTaskMBS, byref error as NSErrorMBS) as boolean
Plugin Version: 7.7, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: Saves the specified
task to the calendar store.
Example:
dim
dim
dim
dim
s as new CalCalendarStoreMBS
t as new CalTaskMBS
a() as CalCalendarMBS = s.calendars
d as new date
d.Month = d.Month + 1
t.calendar = a(0)
t.Title = ”Test”
t.URL = ”http://www.mbsplugins.de/”
t.priority = t.CalPriorityMedium
t.dueDate = d
t.notes = ”just a test”
t.isCompleted = false
dim e as NSErrorMBS
5.5. CLASS CALCALENDARSTOREMBS
89
if s.saveTask(t, e) then
MsgBox ”saved”
else
MsgBox ”failed to save”
end if
Notes:
task: The task to save.
error: If this method returns false, an NSError object describing the error.
Returns true on success; otherwise, returns false and sets the error argument to an NSError object describing
the error.
Use this method to save new task objects and modifications to existing task objects. Changes to task objects
are not persistent until this method is invoked. The calendar property needs to be set before attempting to
save a task.
Available in Mac OS X v10.5 and later.
5.5.21
tasks as CalTaskMBS()
Plugin Version: 11.2, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: This method returns
an array of all the CalTasks.
Notes: This is the function which uses all calendars.
See also:
• 5.5.22 tasks(calendar as CalCalendarMBS) as CalTaskMBS()
89
• 5.5.23 tasks(calendars() as CalCalendarMBS) as CalTaskMBS()
90
5.5.22
tasks(calendar as CalCalendarMBS) as CalTaskMBS()
Plugin Version: 11.2, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: This method returns
an array of all the CalTasks which match the condition.
See also:
• 5.5.21 tasks as CalTaskMBS()
89
• 5.5.23 tasks(calendars() as CalCalendarMBS) as CalTaskMBS()
90
90
CHAPTER 5. CALENDAR
5.5.23
tasks(calendars() as CalCalendarMBS) as CalTaskMBS()
Plugin Version: 11.2, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: This method returns
an array of all the CalTasks which match the condition.
See also:
• 5.5.21 tasks as CalTaskMBS()
89
• 5.5.22 tasks(calendar as CalCalendarMBS) as CalTaskMBS()
89
5.5.24
TasksCompletedSince(completedSince as date) as CalTaskMBS()
Plugin Version: 11.2, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: This method returns
an array of all the CalTasks which match the condition.
Notes: This is the function which uses all calendars.
See also:
• 5.5.25 TasksCompletedSince(completedSince as date, calendar as CalCalendarMBS) as CalTaskMBS()
90
• 5.5.26 TasksCompletedSince(completedSince as date, calendars() as CalCalendarMBS) as CalTaskMBS()
90
5.5.25
TasksCompletedSince(completedSince as date, calendar as CalCalendarMBS) as CalTaskMBS()
Plugin Version: 11.2, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: This method returns
an array of all the CalTasks which match the condition.
See also:
• 5.5.24 TasksCompletedSince(completedSince as date) as CalTaskMBS()
90
• 5.5.26 TasksCompletedSince(completedSince as date, calendars() as CalCalendarMBS) as CalTaskMBS()
90
5.5.26
TasksCompletedSince(completedSince as date, calendars() as CalCalendarMBS) as CalTaskMBS()
Plugin Version: 11.2, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: This method returns
an array of all the CalTasks which match the condition.
See also:
• 5.5.24 TasksCompletedSince(completedSince as date) as CalTaskMBS()
90
• 5.5.25 TasksCompletedSince(completedSince as date, calendar as CalCalendarMBS) as CalTaskMBS()
90
5.5. CLASS CALCALENDARSTOREMBS
5.5.27
91
taskWithUID(UID as string) as CalTaskMBS
Plugin Version: 7.7, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: Searches the task
with the given unique ID.
Notes: Returns nil on any error.
5.5.28
UncompletedTasks as CalTaskMBS()
Plugin Version: 11.2, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: This method returns
an array of all the CalTasks which match the condition.
Example:
dim c as new CalCalendarStoreMBS
dim ta() as CalTaskMBS = c.UncompletedTasks
for each ct as CalTaskMBS in ta
msgbox ct.Title+EndOfLine+str(ct.priority)+EndOfLine+ct.dueDate.LongDate
next
Notes: This is the function which uses all calendars.
See also:
• 5.5.29 UncompletedTasks(calendar as CalCalendarMBS) as CalTaskMBS()
91
• 5.5.30 UncompletedTasks(calendars() as CalCalendarMBS) as CalTaskMBS()
91
5.5.29
UncompletedTasks(calendar as CalCalendarMBS) as CalTaskMBS()
Plugin Version: 11.2, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: This method returns
an array of all the CalTasks which match the condition.
See also:
• 5.5.28 UncompletedTasks as CalTaskMBS()
91
• 5.5.30 UncompletedTasks(calendars() as CalCalendarMBS) as CalTaskMBS()
91
5.5.30
UncompletedTasks(calendars() as CalCalendarMBS) as CalTaskMBS()
Plugin Version: 11.2, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: This method returns
an array of all the CalTasks which match the condition.
See also:
92
CHAPTER 5. CALENDAR
• 5.5.28 UncompletedTasks as CalTaskMBS()
91
• 5.5.29 UncompletedTasks(calendar as CalCalendarMBS) as CalTaskMBS()
91
5.5.31
UncompletedTasksDueBefore(dueDate as date) as CalTaskMBS()
Plugin Version: 11.2, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: This method returns
an array of all the CalTasks which match the condition.
Notes: This is the function which uses all calendars.
See also:
• 5.5.32 UncompletedTasksDueBefore(dueDate as date, calendar as CalCalendarMBS) as CalTaskMBS()
92
• 5.5.33 UncompletedTasksDueBefore(dueDate as date, calendars() as CalCalendarMBS) as CalTaskMBS()
92
5.5.32
UncompletedTasksDueBefore(dueDate as date, calendar as CalCalendarMBS) as CalTaskMBS()
Plugin Version: 11.2, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: This method returns
an array of all the CalTasks which match the condition.
See also:
• 5.5.31 UncompletedTasksDueBefore(dueDate as date) as CalTaskMBS()
92
• 5.5.33 UncompletedTasksDueBefore(dueDate as date, calendars() as CalCalendarMBS) as CalTaskMBS()
92
5.5.33
UncompletedTasksDueBefore(dueDate as date, calendars() as CalCalendarMBS) as CalTaskMBS()
Plugin Version: 11.2, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: This method returns
an array of all the CalTasks which match the condition.
See also:
• 5.5.31 UncompletedTasksDueBefore(dueDate as date) as CalTaskMBS()
92
• 5.5.32 UncompletedTasksDueBefore(dueDate as date, calendar as CalCalendarMBS) as CalTaskMBS()
92
5.5. CLASS CALCALENDARSTOREMBS
5.5.34
Properties
5.5.35
Handle as Integer
93
Plugin Version: 7.7, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: The internal used
CalCalendarStore reference.
Notes: (Read and Write property)
5.5.36
Events
5.5.37
CalendarsChanged(Externally as boolean, InsertedRecords() as string,
UpdatedRecords() as string, DeletedRecords() as string)
Plugin Version: 11.2, Console & Web: No, Mac: Yes, Win: No, Linux: No. Function: The event being
called when some calendars changed.
Notes:
The Calendar Store frameworks posts notifications when any application, including yours, makes changes to
the user’s calendar data.
Externally is true if this changes are not made by your application.
The three events give you the unique IDs of the calendars which have been inserted, updated or modified.
If all three arrays are nil/empty, that indicates everything has changed, and the client should refresh the
calendar, event, and task information currently being used. Since this tends to be an expensive and inconvenient operation, it will only occur under unusual circumstances, such as when restoring from backup.
5.5.38
EventsChanged(Externally as boolean, InsertedRecords() as string, UpdatedRecords() as string, DeletedRecords() as string)
Plugin Version: 11.2, Console & Web: No, Mac: Yes, Win: No, Linux: No. Function: The event being
called when some events changed.
Notes:
The Calendar Store frameworks posts notifications when any application, including yours, makes changes to
the user’s calendar data.
Externally is true if this changes are not made by your application.
94
CHAPTER 5. CALENDAR
The three events give you the unique IDs of the events which have been inserted, updated or modified.
If all three arrays are nil/empty, that indicates everything has changed, and the client should refresh the
calendar, event, and task information currently being used. Since this tends to be an expensive and inconvenient operation, it will only occur under unusual circumstances, such as when restoring from backup.
5.5.39
TasksChanged(Externally as boolean, InsertedRecords() as string, UpdatedRecords() as string, DeletedRecords() as string)
Plugin Version: 11.2, Console & Web: No, Mac: Yes, Win: No, Linux: No. Function: The event being
called when some tasks changed.
Notes:
The Calendar Store frameworks posts notifications when any application, including yours, makes changes to
the user’s calendar data.
Externally is true if this changes are not made by your application.
The three events give you the unique IDs of the tasks which have been inserted, updated or modified.
If all three arrays are nil/empty, that indicates everything has changed, and the client should refresh the
calendar, event, and task information currently being used. Since this tends to be an expensive and inconvenient operation, it will only occur under unusual circumstances, such as when restoring from backup.
5.5.40
Constants
5.5.41
CalSpanAllEvents=2
Plugin Version: 7.7. Function: One of the Calendar Span constants.
5.5.42
CalSpanFutureEvents=1
Plugin Version: 7.7. Function: One of the Calendar Span constants.
5.5. CLASS CALCALENDARSTOREMBS
5.5.43
CalSpanThisEvent=0
Plugin Version: 7.7. Function: One of the Calendar Span constants.
95
96
5.6
5.6.1
CHAPTER 5. CALENDAR
class CalEventMBS
class CalEventMBS
Plugin Version: 7.7, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: The class to handle
events in iCal.
Example:
// start a connection to the calendar database
dim s as new CalCalendarStoreMBS
// needed for the error details
dim e as NSErrorMBS
// create a new event
dim c as new CalEventMBS
// set properties
dim calendars() as CalCalendarMBS = s.calendars
c.Title=”new Event”
c.startDate=new date
c.calendar=calendars(0) // add to first calendar
dim d as new date
d.hour=d.hour+1
c.endDate=d
// save event
call s.saveEvent(c,s.CalSpanAllEvents, e)
if e<>nil then
MsgBox e.localizedDescription
else
MsgBox ”New event was created.”
end if
Notes:
Requires Mac OS X 10.5 to work.
Subclass of the CalCalendarItemMBS class.
5.6. CLASS CALEVENTMBS
5.6.2
Methods
5.6.3
attendees as CalAttendeeMBS()
97
Plugin Version: 7.7, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: The attendees for
this event.
Notes: It is not possible to modify an event’s attendees in Mac OS X 10.5.
5.6.4
Constructor
Plugin Version: 7.7, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: The constructor to
which creates a new event.
Example:
// start a connection to the calendar database
dim s as new CalCalendarStoreMBS
// needed for the error details
dim e as NSErrorMBS
// create a new event
dim c as new CalEventMBS
// set properties
dim calendars() as CalCalendarMBS = s.calendars
c.Title=”new Event”
c.startDate=new date
c.calendar=calendars(0) // add to first calendar
dim d as new date
d.hour=d.hour+1
c.endDate=d
// save event
call s.saveEvent(c,s.CalSpanAllEvents, e)
if e<>nil then
MsgBox e.localizedDescription
else
MsgBox ”New event was created.”
end if
Notes: The calendar property must be set before calling saveTask on a new task.
98
CHAPTER 5. CALENDAR
5.6.5
Properties
5.6.6
endDate as date
Plugin Version: 7.7, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: The end date.
Example:
dim e as CalEventMBS
msgbox e.endDate.longdate+” ”+e.endDate.longtime
Notes:
The client is responsible for making sure they never attempt to save an event with a start date that occurs
after the endDate, or an endDate that occurs before the startDate. Calling saveEvent: on an improperly
configured event will fail.
(Read and Write property)
5.6.7
isAllDay as boolean
Plugin Version: 7.7, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: Whether this event
is all day.
Notes:
True for all day events.
(Read and Write property)
5.6.8
isDetached as boolean
Plugin Version: 7.7, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: Whether this event
is detached.
Notes:
These properties are only meaningful for CalEvents which are instances of a repeating event.
If this CalEvent is an instance of a repeating event, and an attribute of this CalEvent has been changed
to from the default value generated by the repeating event, isDetached will return true. If the CalEvent is
unchanged from its default state, or is not a repeating event, isDetached returns false.
(Read only property)
5.6. CLASS CALEVENTMBS
5.6.9
99
location as string
Plugin Version: 7.7, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: The location of this
event.
Example:
dim c as new CalCalendarStoreMBS
// set the date range where we look for event
dim sd as new date(2016,6,7,0,0,0)
dim ed as new date(2016,6,7,23,59,59)
// look for an event on that date
dim a() as CalEventMBS = c.events(sd,ed, c.calendars)
dim e as CalEventMBS = a(1)
// show location
MsgBox e.location
// change it
e.location = ”Hamburg”
// check again
MsgBox e.location
// Save
dim error as NSErrorMBS
dim ok as Boolean = c.saveEvent(e, c.CalSpanThisEvent, error)
if ok then
MsgBox ”OK”
elseif error <>nil then
MsgBox error.LocalizedDescription
else
MsgBox ”Failed.”
end if
Notes: (Read and Write property)
5.6.10
occurrence as date
Plugin Version: 7.7, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: The ocurrences of
this event.
Notes:
100
CHAPTER 5. CALENDAR
These properties are only meaningful for CalEvents which are instances of a repeating event.
Returns the occurrence date of a CalEvent. Since all instances of a repeating event have the same UID, we
need another way to differentiate between those CalEvents. This method returns the NSDate on which this
event was originally scheduled to occur. This value will remain the same even if the event has been detached
and its start date has changed. For CalEvents not part of a repeating pattern, this method will return the
same value as startDate.
(Read only property)
5.6.11
recurrenceRule as CalRecurrenceRuleMBS
Plugin Version: 8.4, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: The recurrence rule
for this event.
Example:
// create a recurrence event:
dim
dim
dim
dim
dim
dim
dim
c as new CalCalendarStoreMBS
e as new CalEventMBS
error as NSErrorMBS
s as string
ed as new date
rule as CalRecurrenceRuleMBS
rend as CalRecurrenceEndMBS
ed.day=21
ed.Month=7
ed.Year=2008
e.endDate=ed
dim sd as new date
sd.day=18
sd.Month=7
sd.Year=2008
e.startDate=sd
e.isAllDay=true
e.location=”Example Location”
rule=CalRecurrenceRuleMBS.initYearlyRecurrence(1,nil)
dim calendars() as CalCalendarMBS = c.calendars
e.Title=”Example Title”
e.calendar=calendars(0) // pick first calendar
5.6. CLASS CALEVENTMBS
101
e.notes=”Example Notes”
e.URL=”http://www.monkeybreadsoftware.de”
e.recurrenceRule=rule
if c.saveEvent(e, c.CalSpanAllEvents, error) then
if error<>Nil then s=error.localizedDescription
MsgBox ”OK”+EndOfLine+s
else
if error<>Nil then s=error.localizedDescription
MsgBox ”Failed”+EndOfLine+s
end if
Notes:
Set to nil to remove recurrence rule.
(Read and Write property)
5.6.12
startDate as date
Plugin Version: 7.7, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: The start date.
Example:
dim e as CalEventMBS
msgbox e.startDate.longdate+” ”+e.startDate.longtime
Notes:
The client is responsible for making sure they never attempt to save an event with a start date that occurs
after the endDate, or an endDate that occurs before the startDate. Calling saveEvent: on an improperly
configured event will fail.
(Read and Write property)
102
5.7
5.7.1
CHAPTER 5. CALENDAR
class CalNthWeekDayMBS
class CalNthWeekDayMBS
Plugin Version: 7.7, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: CalNthWeekDay
specifies the nth instance of a particular day of the week, such as the third Tuesday of every month.
Notes:
Requires Mac OS X 10.5 to work.
This is an abstract class. You can’t create an instance, but you can get one from various plugin functions.
5.7.2
Methods
5.7.3
Constructor
Plugin Version: 13.1, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: The private constructor.
5.7.4
Properties
5.7.5
dayOfTheWeek as Integer
Plugin Version: 7.7, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: The day of the week.
Notes:
Valid values for dayOfTheWeek are integers 1-7, which correspond to days of the week with Sunday = 1.
(Read only property)
5.7.6
weekNumber as Integer
Plugin Version: 7.7, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: The week number.
Notes:
Valid values for weekNumber portion are 1, 2, 3, 4, or -1, where a value of -1 indicates the last week.
(Read only property)
5.8. CLASS CALRECURRENCEENDMBS
5.8
5.8.1
103
class CalRecurrenceEndMBS
class CalRecurrenceEndMBS
Plugin Version: 7.7, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: The class to specify
the end of a recurring calendar event.
Notes:
CalRecurrenceEnd is an attribute of CalRecurrenceRule that defines how long the recurrence is scheduled
to repeat.
The recurrence can be defined either with an integer that indicates the total number times it repeats, or with
a date, after which it no longer repeats. An event which is set to never end should have its CalRecurrenceEnd
set to nil.
If the end of the pattern is defines with a date, the client must pass a valid date, nil cannot be passed. If
the end of the pattern is defined as terms of a number of occurrences, the occurrenceCount passed to the
initializer must be positive, it cannot be 0. If the client attempts to initialize a CalRecurrenceEnd with a
nil date or OccurrenceCount of 0, an exception is raised.
A CalRecurrenceEnd initialized with an end date will return 0 for occurrenceCount. One initialized with a
number of occurrences will return nil for its endDate.
Requires Mac OS X 10.5 to work.
5.8.2
Methods
5.8.3
Constructor(endDate as date)
Plugin Version: 7.7, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: The constructor for
a new recurrence end based on an end date.
See also:
• 5.8.4 Constructor(occurrenceCount as Integer)
5.8.4
103
Constructor(occurrenceCount as Integer)
Plugin Version: 7.7, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: The constructor for
a new recurrence end based on an occurrence count.
See also:
• 5.8.3 Constructor(endDate as date)
103
104
CHAPTER 5. CALENDAR
5.8.5
Properties
5.8.6
endDate as date
Plugin Version: 7.7, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: The end date.
Notes:
This property is read only.
(Read only property)
5.8.7
occurrenceCount as Integer
Plugin Version: 7.7, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: The occurrence
count.
Notes:
This property is read only.
(Read only property)
5.8.8
usesEndDate as boolean
Plugin Version: 7.7, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: Whether the end
date is used.
Notes:
This property is read only.
(Read only property)
5.9. CLASS CALRECURRENCERULEMBS
5.9
5.9.1
105
class CalRecurrenceRuleMBS
class CalRecurrenceRuleMBS
Plugin Version: 7.7, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: The class for the
recurrence rules.
Example:
// start a connection to the calendar database
dim s as new CalCalendarStoreMBS
// needed for the error details
dim e as NSErrorMBS
dim r as CalRecurrenceRuleMBS = CalRecurrenceRuleMBS.initYearlyRecurrence(1, nil) // repeat every
year without end
dim a as new CalAlarmMBS // add alarm
a.action = a.CalAlarmActionDisplay
a.relativeTrigger = -3600*24 // 24 Hours before
// create a new calendar
dim c as new CalEventMBS
dim d as new date(2011, 04, 20) // the date
// set properties
dim calendars() as CalCalendarMBS = s.calendars
c.Title=”Test Birthday”
c.startDate=d
c.recurrenceRule = r
c.calendar=calendars(1) // add to second calendar
c.addAlarm(a)
c.endDate = d
c.isAllDay = true
// save event
call s.saveEvent(c,s.CalSpanAllEvents, e)
if e<>nil then
MsgBox e.localizedDescription
else
MsgBox ”New event was created.”
end if
Notes:
106
CHAPTER 5. CALENDAR
Requires Mac OS X 10.5 to work.
This is an abstract class. You can’t create an instance, but you can get one from various plugin functions.
5.9.2
Methods
5.9.3
Constructor
Plugin Version: 13.1, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: The private constructor.
5.9.4
daysOfTheMonth as Integer()
Plugin Version: 11.2, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: This property can
be accessed as an array containing one or more integers corresponding to the days of the month the event
recurs.
Notes:
This property is valid for rules whose CalRecurrenceType is CalMonthlyRecurrence, and that were initialized
with one or more specific days of the month (not with a day of the week and week of the month).
For all other CalRecurrenceRules, this property is empty.
5.9.5
daysOfTheWeek as Integer()
Plugin Version: 11.2, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: This property can
be accessed as an array containing one or more integers corresponding to the days of the week the event
recurs.
Notes: This property is valid for rules whose CalRecurrenceType is CalWeeklyRecurrence. For all other
CalRecurrenceRules, this property is empty.
5.9.6
initDailyRecurrence(interval as Integer, RecurrenceEnd as CalRecurrenceEndMBS)
as CalRecurrenceRuleMBS
Plugin Version: 7.7, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: Daily Recurrence
initializer.
Notes: Two parameters are included in every CalRecurrenceRule initializer. The first is the interval, which
is described above and indicates how many CalRecurrenceTypes make up the period of the recurrence (every
week, every other week, etc.). The second is a CalRecurrenceEnd, which describes when the CalRecurrenceRule ends. If valid values for these two parameters are not included, nil is returned. There are simple
5.9. CLASS CALRECURRENCERULEMBS
107
initializers for each CalRecurrenceType which take only these two parameters.
5.9.7
initMonthlyRecurrence(interval as Integer, DayOfTheWeek as Integer,
WeekOfTheMonth as Integer, RecurrenceEnd as CalRecurrenceEndMBS)
as CalRecurrenceRuleMBS
Plugin Version: 7.7, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: Monthly Recurrence
initializer.
Notes:
This initializer allows the client to specify a repeating monthly pattern in terms of a day of the week and a
week of the month that the even repeats. An example is an event that recurs the first Monday of every month.
Two parameters are included in every CalRecurrenceRule initializer. The first is the interval, which is described above and indicates how many CalRecurrenceTypes make up the period of the recurrence (every
week, every other week, etc.). The second is a CalRecurrenceEnd, which describes when the CalRecurrenceRule ends. If valid values for these two parameters are not included, nil is returned. There are simple
initializers for each CalRecurrenceType which take only these two parameters.
Valid values for days of the week are integers 1-7, which correspond to days of the week with Sunday = 1.
Valid values for weeks of the month are integers 1-4 and -1, which is used to indicate the last week of the
month.
See also:
• 5.9.8 initMonthlyRecurrence(interval as Integer, DaysOfTheMonth() as Integer, RecurrenceEnd as
CalRecurrenceEndMBS) as CalRecurrenceRuleMBS
107
• 5.9.9 initMonthlyRecurrence(interval as Integer, RecurrenceEnd as CalRecurrenceEndMBS) as CalRecurrenceRuleMBS
108
5.9.8
initMonthlyRecurrence(interval as Integer, DaysOfTheMonth() as Integer, RecurrenceEnd as CalRecurrenceEndMBS) as CalRecurrenceRuleMBS
Plugin Version: 7.7, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: Monthly Recurrence
initializer.
Notes:
This initializer allows the client to specify multiple days of the month that an event will recur. This method
should be used to initialize events that occur more than once a month, in a set monthly pattern.
Two parameters are included in every CalRecurrenceRule initializer. The first is the interval, which is described above and indicates how many CalRecurrenceTypes make up the period of the recurrence (every
week, every other week, etc.). The second is a CalRecurrenceEnd, which describes when the CalRecurrenceRule ends. If valid values for these two parameters are not included, nil is returned. There are simple
108
CHAPTER 5. CALENDAR
initializers for each CalRecurrenceType which take only these two parameters.
Valid values for days of the month are integers 1-31.
See also:
• 5.9.7 initMonthlyRecurrence(interval as Integer, DayOfTheWeek as Integer, WeekOfTheMonth as Integer, RecurrenceEnd as CalRecurrenceEndMBS) as CalRecurrenceRuleMBS
107
• 5.9.9 initMonthlyRecurrence(interval as Integer, RecurrenceEnd as CalRecurrenceEndMBS) as CalRecurrenceRuleMBS
108
5.9.9
initMonthlyRecurrence(interval as Integer, RecurrenceEnd as CalRecurrenceEndMBS) as CalRecurrenceRuleMBS
Plugin Version: 7.7, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: Monthly Recurrence
initializer.
Notes: Two parameters are included in every CalRecurrenceRule initializer. The first is the interval, which
is described above and indicates how many CalRecurrenceTypes make up the period of the recurrence (every
week, every other week, etc.). The second is a CalRecurrenceEnd, which describes when the CalRecurrenceRule ends. If valid values for these two parameters are not included, nil is returned. There are simple
initializers for each CalRecurrenceType which take only these two parameters.
See also:
• 5.9.7 initMonthlyRecurrence(interval as Integer, DayOfTheWeek as Integer, WeekOfTheMonth as Integer, RecurrenceEnd as CalRecurrenceEndMBS) as CalRecurrenceRuleMBS
107
• 5.9.8 initMonthlyRecurrence(interval as Integer, DaysOfTheMonth() as Integer, RecurrenceEnd as
CalRecurrenceEndMBS) as CalRecurrenceRuleMBS
107
5.9.10
initWeeklyRecurrence(interval as Integer, DaysOfTheWeek() as Integer,
RecurrenceEnd as CalRecurrenceEndMBS) as CalRecurrenceRuleMBS
Plugin Version: 7.7, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: Weekly Recurrence
initializers.
Notes:
This initializer allows the client to specify multiple days of the week that an event will recur. This initializer
should be used to initialize events that occur more than once a week, in a set weekly pattern.
Two parameters are included in every CalRecurrenceRule initializer. The first is the interval, which is described above and indicates how many CalRecurrenceTypes make up the period of the recurrence (every
week, every other week, etc.). The second is a CalRecurrenceEnd, which describes when the CalRecurrenceRule ends. If valid values for these two parameters are not included, nil is returned. There are simple
initializers for each CalRecurrenceType which take only these two parameters.
5.9. CLASS CALRECURRENCERULEMBS
109
Valid values for days of the week are integers 1-7, which correspond to days of the week with Sunday = 1.
See also:
• 5.9.11 initWeeklyRecurrence(interval as Integer, RecurrenceEnd as CalRecurrenceEndMBS) as CalRecurrenceRuleMBS
109
5.9.11
initWeeklyRecurrence(interval as Integer, RecurrenceEnd as CalRecurrenceEndMBS) as CalRecurrenceRuleMBS
Plugin Version: 7.7, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: Weekly Recurrence
initializers.
Notes: Two parameters are included in every CalRecurrenceRule initializer. The first is the interval, which
is described above and indicates how many CalRecurrenceTypes make up the period of the recurrence (every
week, every other week, etc.). The second is a CalRecurrenceEnd, which describes when the CalRecurrenceRule ends. If valid values for these two parameters are not included, nil is returned. There are simple
initializers for each CalRecurrenceType which take only these two parameters.
See also:
• 5.9.10 initWeeklyRecurrence(interval as Integer, DaysOfTheWeek() as Integer, RecurrenceEnd as CalRecurrenceEndMBS) as CalRecurrenceRuleMBS
108
5.9.12
initYearlyRecurrence(interval as Integer, DayOfTheWeek as Integer, WeekOfTheMonth as Integer, MonthsOfTheYear() as Integer, RecurrenceEnd as
CalRecurrenceEndMBS) as CalRecurrenceRuleMBS
Plugin Version: 7.7, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: Yearly Recurrence
initializer.
Notes:
This initializer allows the client to specify multiple months of the year that an event will recur. This method
should be used to initialize events that recur on the same day of the week, in the same week of a month,
of possibly more than one month a year, in a set yearly pattern. An example is an event that occurs every
year on the last Friday of sixth and twelfth months.
Two parameters are included in every CalRecurrenceRule initializer. The first is the interval, which is described above and indicates how many CalRecurrenceTypes make up the period of the recurrence (every
week, every other week, etc.). The second is a CalRecurrenceEnd, which describes when the CalRecurrenceRule ends. If valid values for these two parameters are not included, nil is returned. There are simple
initializers for each CalRecurrenceType which take only these two parameters.
Valid values for days of the week are integers 1-7, which correspond to days of the week with Sunday = 1.
Valid values for weeks of the month are integers 1-4 and -1, which is used to indicate the last week of the
month.
Valid values for months of the year are integers 1-12, which correspond to months of the year with January
110
CHAPTER 5. CALENDAR
= 1.
See also:
• 5.9.13 initYearlyRecurrence(interval as Integer, MonthsOfTheYear() as Integer, RecurrenceEnd as CalRecurrenceEndMBS) as CalRecurrenceRuleMBS
110
• 5.9.14 initYearlyRecurrence(interval as Integer, RecurrenceEnd as CalRecurrenceEndMBS) as CalRecurrenceRuleMBS
110
5.9.13
initYearlyRecurrence(interval as Integer, MonthsOfTheYear() as Integer, RecurrenceEnd as CalRecurrenceEndMBS) as CalRecurrenceRuleMBS
Plugin Version: 7.7, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: Yearly Recurrence
initializer.
Notes:
This initializer allows the client to specify multiple months of the year that an event will recur. This method
should be used to initialize events that occur on the same date, in more than month a year, in a set monthly
pattern. An example is an event that occurs every year on the first day of the first and seventh months.
Two parameters are included in every CalRecurrenceRule initializer. The first is the interval, which is described above and indicates how many CalRecurrenceTypes make up the period of the recurrence (every
week, every other week, etc.). The second is a CalRecurrenceEnd, which describes when the CalRecurrenceRule ends. If valid values for these two parameters are not included, nil is returned. There are simple
initializers for each CalRecurrenceType which take only these two parameters.
Valid values for months of the year are integers 1-12, which correspond to months of the year with January
= 1.
See also:
• 5.9.12 initYearlyRecurrence(interval as Integer, DayOfTheWeek as Integer, WeekOfTheMonth as Integer, MonthsOfTheYear() as Integer, RecurrenceEnd as CalRecurrenceEndMBS) as CalRecurrenceRuleMBS
109
• 5.9.14 initYearlyRecurrence(interval as Integer, RecurrenceEnd as CalRecurrenceEndMBS) as CalRecurrenceRuleMBS
110
5.9.14
initYearlyRecurrence(interval as Integer, RecurrenceEnd as CalRecurrenceEndMBS) as CalRecurrenceRuleMBS
Plugin Version: 7.7, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: Yearly Recurrence
initializer.
Example:
// create a recurrence event:
5.9. CLASS CALRECURRENCERULEMBS
dim
dim
dim
dim
dim
dim
dim
111
c as new CalCalendarStoreMBS
e as new CalEventMBS
error as NSErrorMBS
s as string
ed as new date
rule as CalRecurrenceRuleMBS
rend as CalRecurrenceEndMBS
ed.day=21
ed.Month=7
ed.Year=2008
e.endDate=ed
dim sd as new date
sd.day=18
sd.Month=7
sd.Year=2008
e.startDate=sd
e.isAllDay=true
e.location=”Example Location”
rule=CalRecurrenceRuleMBS.initYearlyRecurrence(1,nil)
dim calendars() as CalCalendarMBS = c.calendars
e.Title=”Example Title”
e.calendar=calendars(0) // pick first calendar
e.notes=”Example Notes”
e.URL=”http://www.monkeybreadsoftware.de”
e.recurrenceRule=rule
if c.saveEvent(e, c.CalSpanAllEvents, error) then
if error<>Nil then s=error.localizedDescription
MsgBox ”OK”+EndOfLine+s
else
if error<>Nil then s=error.localizedDescription
MsgBox ”Failed”+EndOfLine+s
end if
Notes: Two parameters are included in every CalRecurrenceRule initializer. The first is the interval, which
is described above and indicates how many CalRecurrenceTypes make up the period of the recurrence (every
week, every other week, etc.). The second is a CalRecurrenceEnd, which describes when the CalRecurrenceRule ends. If valid values for these two parameters are not included, nil is returned. There are simple
112
CHAPTER 5. CALENDAR
initializers for each CalRecurrenceType which take only these two parameters.
See also:
• 5.9.12 initYearlyRecurrence(interval as Integer, DayOfTheWeek as Integer, WeekOfTheMonth as Integer, MonthsOfTheYear() as Integer, RecurrenceEnd as CalRecurrenceEndMBS) as CalRecurrenceRuleMBS
109
• 5.9.13 initYearlyRecurrence(interval as Integer, MonthsOfTheYear() as Integer, RecurrenceEnd as CalRecurrenceEndMBS) as CalRecurrenceRuleMBS
110
5.9.15
monthsOfTheYear as Integer()
Plugin Version: 11.2, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: This property can
be accessed as an array containing one or more integer corresponding to the months of the year the event
recurs.
Notes: This property is valid for rules whose CalRecurrenceType is CalYearlyRecurrence. For all other
CalRecurrenceRules, this property is empty.
5.9.16
nthWeekDaysOfTheMonth as CalNthWeekDayMBS()
Plugin Version: 11.2, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: This property can
be accessed as an array containing exactly one CalNthWeekDay corresponding to the week of the month the
event recurs.
Notes: This property is valid for rules whose CalRecurrenceType is CalMonthlyRecurrence or CalYearlyRecurrence, and that were initialized with a day of the week and week of the month. For all other
CalRecurrenceRules, this property is empty.
5.9.17
Properties
5.9.18
firstDayOfTheWeek as Integer
Plugin Version: 7.7, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: The first day of the
week.
Notes:
Recurrence patterns can specify which day of the week should be treated as the first day. Possible values for
this property are integers 0 and 1-7, which correspond to days of the week with Sunday = 1. Zero indicates
that the property is not set for this recurrence. he first day of the week only affects the way the recurrence
is expanded for weekly recurrence patterns with an interval greater than 1. For those types of recurrence
patterns, the CalendarStore framework will set firstDayOfTheWeek to be 2 (Monday). In all other cases,
this property will be set to zero. The iCalendar spec stipulates that the default value is Monday if this
property is not set.
5.9. CLASS CALRECURRENCERULEMBS
113
(Read only property)
5.9.19
Handle as Integer
Plugin Version: 7.7, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: The internal used
CalRecurrenceRule reference.
Notes: (Read and Write property)
5.9.20
recurrenceEnd as CalRecurrenceEndMBS
Plugin Version: 7.7, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: This property defines
when the the repeating event is scheduled to end.
Notes:
The end date can be specified by a number of occurrences, or with an end date.
Value can be nil.
This is a read only property.
(Read only property)
5.9.21
recurrenceInterval as Integer
Plugin Version: 7.7, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: Specifies how often
the rule repeats over the given recurrence type.
Notes:
An interval of 1 indicates that the event repeats every time unit, while an interval of 2 indicates that the
repetition occurs in every other unit, etc.
This is a read only property.
(Read only property)
5.9.22
recurrenceType as Integer
Plugin Version: 7.7, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: This property
designates the unit of time used to describe the recurrence pattern.
Notes:
CalRecurrenceType designates the unit of time used to describe the recurrence. It has four possible values,
which correspond to recurrence rules that are defined in terms of days, weeks, months, and years.
114
CHAPTER 5. CALENDAR
The interval of a CalRecurrenceRule is an Integer which specifies how often the recurrence rule repeats over
the unit of time described by the CalRecurrenceType. For example, if the CalRecurrenceType is CalWeeklyRecurrence, then an interval of 1 means the pattern is repeated every week. A NSUInteger of 2 indicates it
is repeated every other week, 3 means every third week, and so on. The Integer must be a positive integer;
0 is not a valid value, and nil will be returned if the client attempts to initialize a rule with a negative or
zero interval.
Together, CalRecurrenceType and interval define how often the CalRecurrenceRule’s pattern repeats.
This is a read only property.
(Read only property)
5.9.23
Constants
5.9.24
CalRecurrenceDaily=0
Plugin Version: 7.7. Function: One of the recurrence type constants.
5.9.25
CalRecurrenceMonthly=2
Plugin Version: 7.7. Function: One of the recurrence type constants.
5.9.26
CalRecurrenceWeekly=1
Plugin Version: 7.7. Function: One of the recurrence type constants.
5.9.27
CalRecurrenceYearly=3
Plugin Version: 7.7. Function: One of the recurrence type constants.
5.10. CLASS CALTASKMBS
5.10
class CalTaskMBS
5.10.1
class CalTaskMBS
115
Plugin Version: 7.7, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: The class for tasks
in iCal.
Example:
dim calStore as new CalCalendarStoreMBS
dim err as NSErrorMBS ’ needed for the error details
dim newTask as new CalTaskMBS ’ create a new reminder
// find existign tasks
dim tasks() as CalTaskMBS = calStore.tasks
// set properties
newTask.Title=”new reminder”
newTask.Priority=9
newTask.DueDate=new date
//
newTask.calendar = tasks(0).calendar ’ add to first List of reminders
call calStore.saveTask(newTask,err) ’ save reminder
if err<>nil then
MsgBox err.localizedDescription
else
MsgBox ”New reminder was created.”
end if
Notes:
Requires Mac OS X 10.5 to work.
Subclass of the CalCalendarItemMBS class.
5.10.2
Methods
5.10.3
Constructor
Plugin Version: 7.7, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: The constructor to
create a new empty task.
Example:
116
dim
dim
dim
dim
CHAPTER 5. CALENDAR
s as new CalCalendarStoreMBS
t as new CalTaskMBS
a() as CalCalendarMBS = s.calendars
d as new date
d.Month = d.Month + 1
t.calendar = a(0)
t.Title = ”Test”
t.URL = ”http://www.mbsplugins.de/”
t.priority = t.CalPriorityMedium
t.dueDate = d
t.notes = ”just a test”
t.isCompleted = false
dim e as NSErrorMBS
if s.saveTask(t, e) then
MsgBox ”saved”
else
MsgBox ”failed to save”
end if
Notes: The calendar property must be set before calling saveTask on a new task.
5.10.4
Properties
5.10.5
completedDate as date
Plugin Version: 7.7, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: The date the task
was completed.
Notes:
The properties isCompleted and CompletedDate are inextricably linked. Setting isCompleted to be true,
will set the completedDate to be now, and setting any completedDate will change isCompleted to be true.
Similarly, setting isCompleted to be false will set the completedDate to be nil, and setting the completedDate
changes isCompleted to false.
(Read and Write property)
5.10.6
dueDate as date
Plugin Version: 7.7, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: The date the task is
due.
5.10. CLASS CALTASKMBS
117
Example:
dim c as new CalCalendarStoreMBS
dim i,count as Integer
dim ta() as CalTaskMBS
dim ct as CalTaskMBS
ta=c.UncompletedTasks
for each ct in ta
msgbox ct.Title+EndOfLine+str(ct.priority)+EndOfLine+ct.dueDate.LongDate
next
Notes: (Read and Write property)
5.10.7
isCompleted as Boolean
Plugin Version: 7.7, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: Whether the task
has been completed.
Notes:
The properties isCompleted and CompletedDate are inextricably linked. Setting isCompleted to be true,
will set the completedDate to be now, and setting any completedDate will change isCompleted to be true.
Similarly, setting isCompleted to be false will set the completedDate to be nil, and setting the completedDate
changes isCompleted to false.
(Read and Write property)
5.10.8
priority as Integer
Plugin Version: 7.7, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: The priority of this
task.
Notes:
The iCalendar specification allows priority to be specified with an integer in the range of 0-9, with 0 representing an undefined priority, 1 the highest priority, and 9 the lowest priority. When a user sets the priority
to high, medium or low in iCal saves the priority as 1, 5, or 9 respectively. Clients are encouraged to use
these values when setting a task’s priority, but is is possible to specify any integer value from 0 to 9. In iCal,
a task with a priority in the range of 1-4 will show up as high priority, a task with a priority of 5 will be
displayed as having medium priority, and 6-9 will be displayed as having a low priority.
(Read and Write property)
118
5.10.9
5.10.10
CHAPTER 5. CALENDAR
Constants
CalPriorityHigh=1
Plugin Version: 7.7. Function: One of the constants for the priority property.
5.10.11
CalPriorityLow=9
Plugin Version: 7.7. Function: One of the constants for the priority property.
5.10.12
CalPriorityMedium=5
Plugin Version: 7.7. Function: One of the constants for the priority property.
5.10.13
CalPriorityNone=0
Plugin Version: 7.7. Function: One of the constants for the priority property.
Chapter 6
Cocoa
6.1
6.1.1
control CocoaControlMBS
control CocoaControlMBS
Plugin Version: 8.4, Console & Web: No, Mac: Yes, Win: No, Linux: No. Function: The control to embed
NSViews into a REALbasic window.
Notes:
Due the way Cocoa event handling works, the keydown event handler (and others) do not work with this
control. To actually get an event, you’d have to use a subclass of CustomNSViewMBS and handle events
there. In the CustomNSViewMBS you add the actual view you like to have. So all events not handled by
this view, fall through to your CustomNSViewMBS.
On Carbon the RS framework intercepts events and calls keydown event.
Requires the window being composite for Carbon targets which is currently not available for modal windows
in Real Studio.
6.1.2
Properties
6.1.3
Available as Boolean
Plugin Version: 8.4, Console & Web: No, Mac: Yes, Win: No, Linux: No. Function: Whether this control
can work.
Notes:
Returns true on Mac OS X 10.5 (or newer) and false on any other OS.
(Read only property)
119
120
6.1.4
CHAPTER 6. COCOA
View as NSViewMBS
Plugin Version: 8.4, Console & Web: No, Mac: Yes, Win: No, Linux: No. Function: The view used with
this control.
Notes:
You define this view in the GetView event.
(Read only property)
6.1.5
WantsFocus as Boolean
Plugin Version: 13.2, Console & Web: No, Mac: Yes, Win: No, Linux: No. Function: Whether this control
wants to have focus.
Notes:
By default this is true.
(Read and Write property)
6.1.6
Events
6.1.7
EnableMenuItems
Plugin Version: 17.1, Console & Web: No, Mac: Yes, Win: Yes, Linux: Yes. Function: The event where
you can enable menu items.
6.1.8
GetView as NSViewMBS
Plugin Version: 8.4, Console & Web: No, Mac: Yes, Win: No, Linux: No. Function: Asks your application
which NSView should be used.
Example:
// an example on how to use this event:
Function GetView() As NSViewMBS
dim n as NSTextViewMBS
// create a textview:
n=new NSTextViewMBS(0, 0, CocoaControlMBS1.Width, CocoaControlMBS1.Height)
n.ContinuousSpellCheckingEnabled=true
Return n
6.1. CONTROL COCOACONTROLMBS
121
End Function
Notes:
Return a NSView setup as you like.
You may also want to keep a reference to the view you use for easier access.
6.1.9
MenuAction(HitItem as MenuItem) As Boolean
Plugin Version: 17.1, Console & Web: No, Mac: Yes, Win: No, Linux: No. Function: Called when a
menuitem is choosen.
Notes: This allows the control to react on its relevant menu items. Please return true if you handled it or
false to give others a chance.
6.1.10
MouseDown(x as Integer, y as Integer, Modifiers as Integer) As Boolean
Plugin Version: 17.1, Console & Web: No, Mac: Yes, Win: No, Linux: No. Function: The mouse button
was pressed inside the controls region at the location passed in to x, y.
Notes:
The coordinates x and y are local to the control, i.e. they represent the position of the mouse click relative
to the upper-left corner or the Control.
Return True if you are going to handle the MouseDown. In such a case:
• The Action event, if any, will not execute and the state of the object will not change.
• You will receive the MouseDrag and MouseUp events.
If you return False, the system handles the MouseDown so the above event handlers do not get called.
6.1.11
MouseDrag(x as Integer, y as Integer)
Plugin Version: 17.1, Console & Web: No, Mac: Yes, Win: No, Linux: No. Function: This event fires
continuously after the mouse button was pressed inside the Control.
Notes:
Mouse location is local to the control passed in to x, y.
As this event is fired continuously (hundreds of time per second), it is your responsibility to determine if the
mouse has really moved.
122
6.1.12
CHAPTER 6. COCOA
MouseUp(x as Integer, y as Integer)
Plugin Version: 17.1, Console & Web: No, Mac: Yes, Win: No, Linux: No. Function: The mouse button
was released.
Notes: Use the x and y parameters to determine if the mouse button was released within the control’s
boundaries.
6.1.13
ScaleFactorChanged(NewFactor as Double)
Plugin Version: 17.1, Console & Web: No, Mac: Yes, Win: No, Linux: No. Function: The backing store
scale factor has changed.
Notes: Please invalidate any cached bitmaps or other relevant state.
6.2. MODULE DICTIONARYSERVICEMBS
6.2
6.2.1
123
module DictionaryServiceMBS
module DictionaryServiceMBS
Plugin Version: 7.7, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: The Dictionary
Services module.
Notes:
Dictionary Services provides functions that let you access dictionaries programmatically from within your
application.
A dictionary is any look-up reference that is built using the Dictionary Development Kit. The contents of a
dictionary can serve many purposes. The most typical use is to provide definitions for a single language, but
you can create content for a thesaurus, bilingual dictionaries (such as English-Japanese), in-house glossaries,
and professional dictionaries (such as legal, medical, and technical).
Available in Mac OS X v10.5 and later.
6.2.2
Methods
6.2.3
GetTermRangeInString(text as string, offset as Integer=0) as boolean
Plugin Version: 7.7, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: Determines the range
of the longest word or phrase with respect to an offset.
Notes:
text: Text that contains the word or phrase to look up.
offset: A character offset in the textString parameter.
Return Value
The range that specifies the location, around the specified offset, of the word or phrase, or the value -1. The
range is stored in the RangePosition and RangeLength properties and the function returns true. On any
error it returns false.
You can use this function to determine the range of text that contains a word or phrase. After you determine
the range, you can pass the result to the functions TextDefinition and Show.
To see how this works, follow these steps:
In Mac OS X v10.5 or later, open Text Edit.
Type It is a foggy day in San Francisco, California.
Control-click Francisco (don’t select it). Then, choose ”Lookup in Dictionary”.
124
CHAPTER 6. COCOA
Note that the Dictionary window appears with a definition of San Francisco. The function GetTermRangeInString automatically detected the range of the phrase San Francisco, using Francisco as the text string to
search for and a character offset in this string. The function expanded the range until it found a possible
match.
You can also point the cursor at the word Francisco and, without making a selection or clicking, type
Command-Control-D. GetTermRangeInString detects the range.
The function GetTermRangeInString only returns the range. You must call TextDefinition to copy the definition and Show to display the definition in a Dictionary window.
Available in Mac OS X v10.5 and later.
6.2.4
RangeLength as Integer
Plugin Version: 7.7, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: The length from the
range.
Notes:
This value set by the GetTermRangeInString function.
(Read and Write computed property)
6.2.5
RangePosition as Integer
Plugin Version: 7.7, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: The position from
the range.
Notes:
This value set by the GetTermRangeInString function.
(Read and Write computed property)
6.2.6
Show(text as string, start as Integer = 0, length as Integer = 0, textOriginX as Double = 0, textOriginY as Double = 0) as boolean
Plugin Version: 7.7, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: Displays dictionary
search result in a dictionary window.
Notes:
text: Text that contains the word or phrase to look up.
6.2. MODULE DICTIONARYSERVICEMBS
125
start and length:
If you are using this function to show the results associated with text selected by the user, then provide
the selection range of the textString parameter. If you are using this function to show the results associated with calling the DCSGetTermRangeInString function, then provide the range returned by that function.
This function opens a window to display the definition of a word or phrase.
Available in Mac OS X v10.5 and later.
6.2.7
TextDefinition(text as string, position as Integer=0, length as Integer=0)
as string
Plugin Version: 7.7, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: Returns the definition
associated with the provided text range.
Notes:
text: Text that contains the word or phrase to look up.
position and length: A range that specifies the location of the word or phrase in the textString parameter.
If text string exactly specifies the word or phrase that you want to look up, you can pass the range of the
text string. For example, for the word make, you would pass (0,4) to specify the range.
If the textString parameter contains the word or phrase, but does not specify it exactly, then pass the range
returned by the function GetTermRangeInString.
Return Value:
The definition of the word or phrase, as plain text. The returned text does not contain any elements that
are marked with a priority attribute whose value is 2.
This function returns the description of the first matching record found in the the active dictionaries. It
searches first in the default word definition dictionary which, in the English environment, is the Oxford
dictionary.
Available in Mac OS X v10.5 and later.
126
6.3
6.3.1
CHAPTER 6. COCOA
class NSAnimationContextMBS
class NSAnimationContextMBS
Plugin Version: 10.0, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: The Cocoa class for
the context of a NSAnimation.
Notes: Available in Mac OS X v10.5 and later.
6.3.2
Methods
6.3.3
beginGrouping
Plugin Version: 10.0, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: Creates a new
animation grouping.
Notes: Available in Mac OS X v10.5 and later.
6.3.4
Constructor
Plugin Version: 10.0, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: Creates a new
NSAnimationContextMBS object with the current animation context.
Notes: Available in Mac OS X v10.5 and later.
6.3.5
currentContext as NSAnimationContextMBS
Plugin Version: 10.0, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: Returns the current
animation context.
Notes: Available in Mac OS X v10.5 and later.
6.3.6
endGrouping
Plugin Version: 10.0, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: Ends the current
animation grouping.
Notes: Available in Mac OS X v10.5 and later.
6.3. CLASS NSANIMATIONCONTEXTMBS
6.3.7
Properties
6.3.8
Handle as Integer
127
Plugin Version: 10.0, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: The internal
reference to the NSAnimationContext object.
Notes: (Read and Write property)
6.3.9
duration as Double
Plugin Version: 10.0, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: The duration used
when animating object properties that support animation.
Example:
NSAnimationContextMBS.currentContext.duration = 0.5
Notes:
Any animations that occur as a result of setting the values of animatable properties in the current context
will run for this duration.
Available in Mac OS X v10.5 and later.
(Read and Write computed property)
128
6.4
6.4.1
CHAPTER 6. COCOA
class NSAnimationMBS
class NSAnimationMBS
Plugin Version: 10.0, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: Objects of the
NSAnimation class manage the timing and progress of animations in the user interface.
Notes:
The class also lets you link together multiple animations so that when one animation ends another one starts.
It does not provide any drawing support for animation and does not directly deal with views, targets, or
actions.
NSAnimation objects have several characteristics, including duration, frame rate, and animation curve, which
describes the relative speed of the animation over its course. You can set progress marks in an animation,
each of which specifies a percentage of the animation completed; when an animation reaches a progress
mark, it notifies its delegate and posts a notification to any observers. Animations execute in one of three
blocking modes: blocking, non-blocking on the main thread, and non-blocking on a separate thread. The
non-blocking modes permit the handling of user events while the animation is running.
6.4.2
Methods
6.4.3
clearStartAnimation
Plugin Version: 10.0, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: Clears linkage to
another animation that causes the receiver to start.
6.4.4
clearStopAnimation
Plugin Version: 10.0, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: Clears linkage to
another animation that causes the receiver to stop.
6.4.5
Constructor(duration as Double, animationCurve as Integer)
Plugin Version: 10.0, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: Initializes the object
with the specified duration and animation-curve values.
Notes:
duration: The number of seconds over which the animation occurs. Specifying a negative number raises an
exception.
animationCurve: An NSAnimationCurve constant that describes the relative speed of the animation over
6.4. CLASS NSANIMATIONMBS
129
its course; if it is zero, the default curve (NSAnimationEaseInOut) is used.
You can always later change the duration of an NSAnimation object by sending it a setDuration: message,
even while the animation is running. See ”Constants” for descriptions of the NSAnimationCurve constants.
6.4.6
currentValue as Double
Plugin Version: 10.0, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: Returns the current
value of the effect based on the current progress.
6.4.7
Destructor
Plugin Version: 13.5, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: The destructor.
6.4.8
isAnimating as boolean
Plugin Version: 10.0, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: Returns a Boolean
value that indicates whether the receiver is currently animating.
Notes: True if the receiver is animating, false otherwise.
6.4.9
startAnimation
Plugin Version: 10.0, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: Starts the animation
represented by the receiver.
Notes: The receiver retains itself and is then autoreleased at the end of the animation or when it receives
stopAnimation. If the blocking mode is NSAnimationBlocking, the method only returns after the animation
has completed or the delegate sends it stopAnimation. If the receiver has a progress of 1.0, it starts again
at 0.0.
6.4.10
stopAnimation
Plugin Version: 10.0, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: Stops the animation
represented by the receiver.
Notes: The current progress of the receiver is not reset. When this method is sent to instances of NSViewAnimation (a subclass of NSAnimation) the receiver moves to the end frame location.
130
CHAPTER 6. COCOA
6.4.11
Properties
6.4.12
Handle as Integer
Plugin Version: 10.0, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: The internal
reference to the animation object.
Notes: (Read and Write property)
6.4.13
animationBlockingMode as Integer
Plugin Version: 10.0, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: The blocking mode
of the receiver.
Notes:
A constant representing the blocking mode the animation is next scheduled to run under. See ”NSAnimationBlockingMode” for valid values.
If the constant is NSAnimationNonblocking, the animation runs in the main thread in one of the standard
run-loop modes or in a mode returned from runLoopModesForAnimating. If animationBlockingMode is
NSAnimationNonblockingThreaded, a new thread is spawned to run the animation.
The default mode is NSAnimationBlocking, which means that the animation runs on the main thread in
a custom run-loop mode that blocks user events. The new blocking mode takes effect the next time the
receiver is started and has no effect on an animation underway.
(Read and Write computed property)
6.4.14
animationCurve as Integer
Plugin Version: 10.0, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: The animation
curve the receiver is running under.
Notes:
The animation curve describes the relative frame rate over the course of the animation. See NSAnimation*
constants.
(Read and Write computed property)
6.4.15
currentProgress as Double
Plugin Version: 10.0, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: The current progress
of the receiver.
Notes:
6.4. CLASS NSANIMATIONMBS
131
The current progress is a value between 0.0 and 1.0 that represents the percentage of the animation currently
completed.
(Read and Write computed property)
6.4.16
duration as Double
Plugin Version: 10.0, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: The duration of the
animation, in seconds.
Notes: (Read and Write computed property)
6.4.17
frameRate as Double
Plugin Version: 10.0, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: The frame rate of
the animation.
Notes:
The frame rate is the number of updates per second. It is not guaranteed to be accurate because of differences between systems on the time needed to process a frame.
(Read and Write computed property)
6.4.18
Events
6.4.19
CurrentProgressChanged(progress as Double)
Plugin Version: 10.0, Console & Web: No, Mac: Yes, Win: No, Linux: No. Function: The event called
whenever the current value changes.
6.4.20
Constants
6.4.21
NSAnimationBlocking=0
Plugin Version: 10.0. Function: One of the constants to indicate the blocking mode of an NSAnimation
object when it is running.
Notes:
Requests the animation to run in the main thread in a custom run-loop mode that blocks user input.
This is the default.
132
6.4.22
CHAPTER 6. COCOA
NSAnimationEaseIn=1
Plugin Version: 10.0. Function: One of the constants to describe the curve of an animationthat is, the
relative speed of an animation from start to finish.
Notes: Describes an animation that slows down as it reaches the end.
6.4.23
NSAnimationEaseInOut=0
Plugin Version: 10.0. Function: One of the constants to describe the curve of an animationthat is, the
relative speed of an animation from start to finish.
Notes: Describes an S-curve in which the animation slowly speeds up and then slows down near the end of
the animation. This constant is the default.
6.4.24
NSAnimationEaseOut=2
Plugin Version: 10.0. Function: One of the constants to describe the curve of an animationthat is, the
relative speed of an animation from start to finish.
Notes: Describes an animation that slowly speeds up from the start.
6.4.25
NSAnimationLinear=3
Plugin Version: 10.0. Function: One of the constants to describe the curve of an animationthat is, the
relative speed of an animation from start to finish.
Notes: Describes an animation in which there is no change in frame rate.
6.4.26
NSAnimationNonblocking=1
Plugin Version: 10.0. Function: One of the constants to indicate the blocking mode of an NSAnimation
object when it is running.
Notes: Requests the animation to run in a standard or specified run-loop mode that allows user input.
6.4.27
NSAnimationNonblockingThreaded=2
Plugin Version: 10.0. Function: One of the constants to indicate the blocking mode of an NSAnimation
object when it is running.
Notes:
6.4. CLASS NSANIMATIONMBS
Requests the animation to run in a separate thread that is spawned by the NSAnimation object.
The secondary thread has its own run loop.
133
134
6.5
6.5.1
CHAPTER 6. COCOA
control WebViewControlMBS
control WebViewControlMBS
Plugin Version: 8.4, Console & Web: No, Mac: Yes, Win: No, Linux: No. Function: The control for a
webview.
Notes: Requires the window being composite for Carbon targets which is currently not available for modal
windows in Real Studio.
6.5.2
Properties
6.5.3
Available as Boolean
Plugin Version: 8.4, Console & Web: No, Mac: Yes, Win: No, Linux: No. Function: Whether this control
can work.
Notes:
Returns true on Mac OS X 10.5 (or newer) and false on any other OS.
(Read only property)
6.5.4
View as WebViewMBS
Plugin Version: 8.4, Console & Web: No, Mac: Yes, Win: No, Linux: No. Function: The view used with
this control.
Example:
dim w as WebViewMBS = WebViewControlMBS1.View
w.LoadURL ”http://www.apple.com”
Notes:
The view object is created for you in the constructor.
In version 9.6 it is a WebViewMBS object.
If you have a version declared as NSViewMBS, you need to cast to WebViewMBS yourself.
(Read only property)
6.5.5
WantsFocus as Boolean
Plugin Version: 13.2, Console & Web: No, Mac: Yes, Win: No, Linux: No. Function: Whether this control
wants to have focus.
6.5. CONTROL WEBVIEWCONTROLMBS
135
Notes:
By default this is true.
(Read and Write property)
6.5.6
Events
6.5.7
EnableMenuItems
Plugin Version: 17.1, Console & Web: No, Mac: Yes, Win: Yes, Linux: Yes. Function: The event where
you can enable menu items.
6.5.8
MenuAction(HitItem as MenuItem) As Boolean
Plugin Version: 17.1, Console & Web: No, Mac: Yes, Win: No, Linux: No. Function: Called when a
menuitem is choosen.
Notes: This allows the control to react on its relevant menu items. Please return true if you handled it or
false to give others a chance.
6.5.9
MouseDown(x as Integer, y as Integer, Modifiers as Integer) As Boolean
Plugin Version: 17.1, Console & Web: No, Mac: Yes, Win: No, Linux: No. Function: The mouse button
was pressed inside the controls region at the location passed in to x, y.
Notes:
The coordinates x and y are local to the control, i.e. they represent the position of the mouse click relative
to the upper-left corner or the Control.
Return True if you are going to handle the MouseDown. In such a case:
• The Action event, if any, will not execute and the state of the object will not change.
• You will receive the MouseDrag and MouseUp events.
If you return False, the system handles the MouseDown so the above event handlers do not get called.
6.5.10
MouseDrag(x as Integer, y as Integer)
Plugin Version: 17.1, Console & Web: No, Mac: Yes, Win: No, Linux: No. Function: This event fires
continuously after the mouse button was pressed inside the Control.
Notes:
136
CHAPTER 6. COCOA
Mouse location is local to the control passed in to x, y.
As this event is fired continuously (hundreds of time per second), it is your responsibility to determine if the
mouse has really moved.
6.5.11
MouseUp(x as Integer, y as Integer)
Plugin Version: 17.1, Console & Web: No, Mac: Yes, Win: No, Linux: No. Function: The mouse button
was released.
Notes: Use the x and y parameters to determine if the mouse button was released within the control’s
boundaries.
6.5.12
ScaleFactorChanged(NewFactor as Double)
Plugin Version: 17.1, Console & Web: No, Mac: Yes, Win: No, Linux: No. Function: The backing store
scale factor has changed.
Notes: Please invalidate any cached bitmaps or other relevant state.
Chapter 7
Cocoa Controls
7.1
class Control
7.1.1
class Control
Plugin Version: 9.7, Console & Web: No, Mac: Yes, Win: No, Linux: No. Function: The built in Control
class in REALbasic.
7.1.2
Methods
7.1.3
CALayerMBS as CALayerMBS
Plugin Version: 13.1, Console & Web: No, Mac: Yes, Win: No, Linux: No. Function: Returns the Core
Animation layer that the receiver uses as its backing store.
Notes:
Works only in Cocoa target.
Also sets wantsLayer to true for the view to make sure it has a layer.
137
138
CHAPTER 7. COCOA CONTROLS
Chapter 8
Cocoa Threading
8.1
8.1.1
class NSOperationMBS
class NSOperationMBS
Plugin Version: 8.0, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: The class to do
operations in Cocoa.
Notes:
Requires Mac OS X 10.5.
The NSOperation class manages the execution of a single encapsulated task. Operations are typically scheduled by adding them to an operation queue object (an instance of the NSOperationQueue class), although
you can also execute them directly by explicitly invoking their start method.
Operation objects are single-shot objects, that is, they perform their task once. You cannot reuse the same
NSOperation object to perform a task (or a slight variant of the task) multiple times in succession. Attempting to execute an operation that has already finished results in an exception.
When manually executing operations, you are responsible for making sure the object is ready to execute.
Starting an operation that is not in the ready state generally results in an exception being thrown. If you
use an operation queue to manage the execution, the NSOperationQueue object ensures that the operation
is executed only when it is ready.
139
140
CHAPTER 8. COCOA THREADING
8.1.2
Methods
8.1.3
addDependency(op as NSOperationMBS)
Plugin Version: 8.0, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: Makes the receiver
dependent on the completion of the specified operation.
Notes:
op: The operation on which the operation is dependent. The same dependency should not be added more
than once to the operation, and the results of doing so are undefined.
The dependent is not considered ready to execute until all of its dependent operations finish executing. If
the receiver is already executing its task, adding dependencies is unlikely to have any practical effect. This
method may change the isReady and dependencies properties of the dependent.
It is a programmer error to create any circular dependencies among a set of operations. Doing so can cause
a deadlock among the operations and may freeze your program.
Please setup dependencies before you add the operation to a queue. Once the operation is in the queue it
may be executed directly.
8.1.4
cancel
Plugin Version: 8.0, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: Advises the operation
object that it should stop executing its task.
Notes:
This method does not force your operation code to stop. The code for your operation must invoke the
isCancelled method periodically to determine whether the operation should be stopped. Once cancelled, an
operation cannot be restarted.
If the operation is already finished executing, this method has no effect. Canceling an operation that is
currently in an operation queue, but not yet executing, causes it to be removed from the queue (although
not necessarily right away).
8.1.5
Constructor
Plugin Version: 17.2, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: The constructor.
See also:
• 8.1.6 Constructor(Handle as Integer)
141
8.1. CLASS NSOPERATIONMBS
8.1.6
141
Constructor(Handle as Integer)
Plugin Version: 17.2, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: The constructor.
Notes: You can pass in handle to NSOperation object.
See also:
• 8.1.5 Constructor
8.1.7
140
dependencies as NSOperationMBS()
Plugin Version: 8.0, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: the operations on
which the operation is dependent.
Notes: The receiver is not considered ready to execute until all of its dependent operations finish executing.
8.1.8
dependenciesCount as Integer
Plugin Version: 8.0, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: The number of the
dependencies.
8.1.9
dependency(index as Integer) as NSOperationMBS
Plugin Version: 9.6, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: Returns the
dependency at the given index.
Notes:
The receiver is not considered ready to execute until all of its dependent operations finish executing.
Operations are not removed from this dependency list as they finish executing. You can therefore use this
list to track all dependent operations, including those that have already finished executing. The only way
to remove an operation from this list is to use the removeDependency method.
Available in Mac OS X v10.5 and later.
8.1.10
isCancelled as boolean
Plugin Version: 8.0, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: Returns a Boolean
value indicating whether the operation has been cancelled.
Notes:
142
CHAPTER 8. COCOA THREADING
True if the operation was explicitly cancelled by an invocation of the operation’s cancel method; otherwise,
false. This method may return true even if the operation is currently executing.
Discussion
Canceling an operation does not actively stop the operation’s code from executing. An operation object is
responsible for calling this method periodically and stopping itself if the method returns true.
8.1.11
isConcurrent as boolean
Plugin Version: 8.0, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: Returns a Boolean
value indicating whether the operation runs asynchronously.
Notes: True if the operation is asynchronous; otherwise, false if the operation runs synchronously on whatever thread started it. This method returns false by default.
8.1.12
isExecuting as boolean
Plugin Version: 8.0, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: Returns a Boolean
value indicating whether the operation is currently executing.
Notes: True if the operation is executing; otherwise, false if the operation has not been started or is already
finished.
8.1.13
isFinished as boolean
Plugin Version: 8.0, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: A Boolean value
indicating whether the operation is done executing.
Notes: True if the operation is no longer executing; otherwise, false.
8.1.14
isReady as boolean
Plugin Version: 8.0, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: Returns a Boolean
value indicating whether the operation can be performed now.
Notes:
True if the operation can be performed now; otherwise, false.
Operations may not be ready due to dependencies on other operations or because of external conditions
that might prevent needed data from being ready. The NSOperation class manages dependencies on other
operations and reports the readiness of the receiver based on those dependencies.
8.1. CLASS NSOPERATIONMBS
143
Note: If the operation is cancelled before it starts, operations that are dependent on the completion of the
receiver will never become ready.
8.1.15
Lock
Plugin Version: 8.0, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: Locks the semaphore.
Example:
dim o as NSOperationMBS // your operation
dim myarray(-1) as window
o.lock
myarray.append window1
o.unlock
Notes:
You need to pair all calls to REALbasic runtime into lock and unlock to make sure you don’t crash. REALbasic is not reentrant safe, so you need to lock.
Be aware that locking costs performance. You should do locks often, so in the time between two locks another
thread can get a lock. Also you should group locks nearby so you don’t waste too much time waiting for the
lock. Finally you need your main application thread to run nice so it doesn’t lock too much, too.
8.1.16
main
Plugin Version: 8.0, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: Performs the operation’s non-concurrent task.
Notes: This will just call to the work event.
8.1.17
removeDependency(op as NSOperationMBS)
Plugin Version: 8.0, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: Removes the operation’s dependence on the specified operation.
Notes: This method may change the isReady and dependencies properties of the operation.
144
8.1.18
CHAPTER 8. COCOA THREADING
start
Plugin Version: 8.0, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: Begins the execution
of the operation.
Notes: The default implementation of this method configures the execution environment for a non-concurrent
operation and invokes the operation’s main method. As part of the default configuration, this method performs several checks to ensure that the non-concurrent operation can actually run and generates appropriate
KVO notifications for each change in the operation’s state. If the operation’s operation has already been
performed, was cancelled, or is not yet ready to run, this method throws an NSInvalidArgumentException
exception. If the operation is to be performed on a separate thread, this method may return before the
operation itself completes on the other thread.
8.1.19
Unlock
Plugin Version: 8.0, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: Unlocks the
semaphore.
Example:
dim o as NSOperationMBS // your operation
dim myarray(-1) as window
o.lock
myarray.append window1
o.unlock
Notes:
You need to pair all calls to REALbasic runtime into lock and unlock to make sure you don’t crash. REALbasic is not reentrant safe, so you need to lock.
Be aware that locking costs performance. You should do locks often, so in the time between two locks another
thread can get a lock. Also you should group locks nearby so you don’t waste too much time waiting for the
lock. Finally you need your main application thread to run nice so it doesn’t lock too much, too.
8.1.20
waitUntilFinished
Plugin Version: 9.6, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: Spend time waiting
for the operation to finish.
8.1. CLASS NSOPERATIONMBS
8.1.21
Properties
8.1.22
Handle as Integer
145
Plugin Version: 8.0, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: The handle to the
internal used NSOperation reference.
Notes: (Read and Write property)
8.1.23
queuePriority as Integer
Plugin Version: 8.0, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: The priority of the
operation in an operation queue.
Notes:
The relative priority of the operation. The returned value always corresponds to one of the predefined constants. If no priority is explicitly set, this method returns NSOperationQueuePriorityNormal.
You should use priority values only as needed to classify the relative priority of non-dependent operations.
Priority values should not be used to implement dependency management among different operation objects.
If you need to establish dependencies between operations, use the addDependency method instead.
If you attempt to specify a priority value that does not match one of the defined constants, this method
automatically adjusts the value you specify towards the NSOperationQueuePriorityNormal priority, stopping at the first valid constant value. For example, if you specified the value -10, this method would adjust
that value to match the NSOperationQueuePriorityVeryLow constant. Similarly, if you specified +10, this
method would adjust the value to match the NSOperationQueuePriorityVeryHigh constant.
(Read and Write computed property)
8.1.24
threadPriority as Double
Plugin Version: 9.6, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: The thread priority
to use when executing the operation.
Notes:
A floating-point number in the range 0.0 to 1.0, where 1.0 is the highest priority. The default thread priority
is 0.5.
Available in Mac OS X v10.6 and later.
(Read and Write computed property)
146
CHAPTER 8. COCOA THREADING
8.1.25
Events
8.1.26
Close
Plugin Version: 8.0, Console & Web: No, Mac: Yes, Win: No, Linux: No. Function: The event called just
before the operation object is destroyed.
8.1.27
Finished
Plugin Version: 8.0, Console & Web: No, Mac: Yes, Win: No, Linux: No. Function: The event called after
work has finished.
Notes: This event is called on the main thread, so you can do GUI stuff here to show the result.
8.1.28
Open
Plugin Version: 8.0, Console & Web: No, Mac: Yes, Win: No, Linux: No. Function: The event called
when the object is created.
Notes: Called on the main thread.
8.1.29
Work
Plugin Version: 8.0, Console & Web: No, Mac: Yes, Win: No, Linux: No. Function: The event called for
an operation to do the work.
Notes:
You should test isCancelled regularly to see whether operation was cancelled.
Please read on the ThreadMBS.Work event for more details.
(NSOperationMBS is a Mac OS X feature, but the ThreadMBS class, does nearly the same on all platforms)
8.1.30
Constants
8.1.31
NSOperationQueuePriorityHigh=4
Plugin Version: 8.0. Function: One of the constants for the priority property.
Notes: Operations receive high priority for execution.
8.1. CLASS NSOPERATIONMBS
8.1.32
NSOperationQueuePriorityLow=-4
Plugin Version: 8.0. Function: One of the constants for the priority property.
Notes: Operations receive low priority for execution.
8.1.33
NSOperationQueuePriorityNormal=0
Plugin Version: 8.0. Function: One of the constants for the priority property.
Notes: Operations receive the normal priority for execution.
8.1.34
NSOperationQueuePriorityVeryHigh=8
Plugin Version: 8.0. Function: One of the constants for the priority property.
Notes: Operations receive very high priority for execution.
8.1.35
NSOperationQueuePriorityVeryLow=-8
Plugin Version: 8.0. Function: One of the constants for the priority property.
Notes: Operations receive very low priority for execution.
147
148
8.2
8.2.1
CHAPTER 8. COCOA THREADING
class NSOperationQueueMBS
class NSOperationQueueMBS
Plugin Version: 8.0, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: Queues NSOperations
for later execution.
Notes:
Available in Mac OS X v10.5 and later.
The NSOperationQueue class manages a set of NSOperation objects in a priority queue and regulates their
execution. Operations remain in the queue until they are explicitly cancelled or finish executing. An application may create multiple operation queues, with each queue running up to its designated maximum number
of operations.
A specific NSOperation object can be in only one operation queue at a time. Operations within a single
queue coordinate their execution order using both priority levels and inter-operation object dependencies.
Operation objects in different queues can coordinate their execution order using dependencies, which are not
queue-specific.
Inter-operation dependencies provide an absolute execution order for operations. An operation object is not
considered ready to execute until all of its dependent operations have finished executing. For operations that
are ready to execute, the operation queue always executes the one with the highest priority relative to the
other ready operations. For details on how to set priority levels and dependencies, see NSOperation Class
Reference.
You should never manually start an operation while it is sitting in an operation queue. Once added, an
operation stays in its queue until it finishes executing or is cancelled.
8.2.2
Methods
8.2.3
addOperation(op as NSOperationMBS)
Plugin Version: 8.0, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: Adds the specified
operation object to the operation queue.
Notes:
An operation object can be in at most one operation queue at a time and cannot be added if it is currently
executing or finished. This method throws an NSInvalidArgumentException exception if any of these conditions is true.
Once added, the specified operation remains in the queue until it is executed or cancelled.
8.2. CLASS NSOPERATIONQUEUEMBS
149
Please setup dependencies before you add the operation to a queue. Once the operation is in the queue it
may be executed directly.
8.2.4
addOperations(ops() as NSOperationMBS, wait as boolean)
Plugin Version: 9.6, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: Adds the specified
array of operations to the queue.
Notes:
ops: The array of NSOperation objects that you want to add to the receiver.
wait: If true, the current thread is blocked until all of the specified operations finish executing. If false, the
operations are added to the queue and control returns immediately to the caller.
An operation object can be in at most one operation queue at a time and cannot be added if it is currently
executing or finished. This method throws an NSInvalidArgumentException exception if any of those error
conditions are true for any of the operations in the ops parameter.
Once added, the specified operation remains in the queue until it its isFinished method returns true.
Available in Mac OS X v10.6 and later.
8.2.5
areAllOperationsFinished as boolean
Plugin Version: 8.0, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: Returns whether all
operations have been finished.
Notes: True if all operations have finished.
8.2.6
cancelAllOperations
Plugin Version: 8.0, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: Cancels all queued
and executing operations.
Notes: This method sends a cancel message to all operations currently in the queue or executing. Queued
operations are cancelled before they begin executing. If an operation is already executing, it is up to that
operation to recognize the cancellation and stop what it is doing.
150
8.2.7
CHAPTER 8. COCOA THREADING
Constructor
Plugin Version: 8.4, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: The constructor
creating a new operation queue.
Notes: On success the handle property is not 0.
8.2.8
currentQueue as NSOperationQueueMBS
Plugin Version: 9.6, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: Returns the operation
queue that launched the current operation.
Notes:
Returns the operation queue that started the operation or nil if the queue could not be determined.
You can use this method from within a running operation object to get a reference to the operation queue
that started it. Calling this method from outside the context of a running operation typically results in nil
being returned.
Available in Mac OS X v10.6 and later.
8.2.9
isOneOperationExecuting as boolean
Plugin Version: 8.0, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: Whether at least one
operation is still executing.
Notes:
True if one of the operations is executing.
False if no operation is executing.
8.2.10
mainQueue as NSOperationQueueMBS
Plugin Version: 9.6, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: Returns the operation
queue associated with the main thread.
Notes:
The returned queue executes operations serially on the main thread. The main thread’s run loop controls
the execution times of these operations.
Available in Mac OS X v10.6 and later.
8.2. CLASS NSOPERATIONQUEUEMBS
8.2.11
151
operation(index as UInt32) as NSOperationMBS
Plugin Version: 9.6, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: Returns a noperations
currently in the queue at the given index.
Notes:
You can use this method to access the operations queued at any given moment. Operations remain queued
until they finish their task. Therefore, the returned array may contain operations that are either executing
or waiting to be executed.
Available in Mac OS X v10.5 and later.
8.2.12
operationCount as Integer
Plugin Version: 9.6, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: Returns the number
of operations currently in the queue.
Notes:
The value returned by this method reflects the instantaneous number of objects in the queue and changes
as operations are completed. As a result, by the time you use the returned value, the actual number of
operations may be different. You should therefore use this value only for approximate guidance and should
not rely on it for object enumerations or other precise calculations.
Available in Mac OS X v10.6 and later.
8.2.13
operations as NSOperationMBS()
Plugin Version: 8.0, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: The operations
currently in the queue.
8.2.14
waitUntilAllOperationsAreFinished
Plugin Version: 8.0, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: Blocks the current
thread until all of the receiver’s queued and executing operations finish executing.
Notes: When called, this method blocks the current thread and waits for the receiver’s current and pending
operations to finish executing. While the thread is blocked, the receiver continues to launch already queued
operations and monitor those that are executing. During this time, the current thread cannot add operations
to the queue, but other threads may. Once all of the pending operations are finished, this method returns.
152
CHAPTER 8. COCOA THREADING
8.2.15
Properties
8.2.16
Handle as Integer
Plugin Version: 8.0, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: The handle to the
internal used NSOperationQueue reference.
Notes: (Read and Write property)
8.2.17
isSuspended as boolean
Plugin Version: 8.0, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: A Boolean value
indicating whether the receiver is scheduling queued operations for execution.
Notes:
True if operations are being scheduled for execution; otherwise, false.
(Read and Write computed property)
8.2.18
maxConcurrentOperationCount as Integer
Plugin Version: 8.0, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: The maximum
number of concurrent operations that the queue can execute.
Notes: (Read and Write computed property)
8.2.19
name as string
Plugin Version: 9.6, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: The name of this
queue.
Notes:
The default value of this string is ”NSOperationQueue <id>”, where <id>is the memory address of the
operation queue. If you want to know when a queue’s name changes, configure a KVO observer to observe
the name key path of the operation queue.
Available in Mac OS X v10.6 and later.
(Read and Write computed property)
8.2. CLASS NSOPERATIONQUEUEMBS
8.2.20
Constants
8.2.21
NSOperationQueueDefaultMaxConcurrentOperationCount=-1
153
Plugin Version: 8.0. Function: One of the constants to be used with the maxConcurrentOperationCount
property.
Notes: The default maximum number of operations is determined dynamically by the NSOperationQueue
object based on current system conditions.
154
CHAPTER 8. COCOA THREADING
Chapter 9
CoreAnimation
9.1
9.1.1
class CALayerMBS
class CALayerMBS
Plugin Version: 13.1, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: The plugin class for
a CoreAnimation.
Notes:
The CALayer class manages image-based content and allows you to perform animations on that content.
Layers are often used to provide the backing store for views but can also be used without a view to display
content. A layer’s main job is to manage the visual content that you provide but the layer itself has visual
attributes that can be set, such as a background color, border, and shadow. In addition to managing visual
content, the layer also maintains information about the geometry of its content (such as its position, size,
and transform) that is used to present that content onscreen. Modifying the properties of the layer is how
you initiate animations on the layer’s content or geometry. A layer object encapsulates the duration and
pacing of a layer and its animations by adopting the CAMediaTiming protocol, which defines the layer’s
timing information.
If the layer object was created by a view, the view typically assigns itself as the layer’s delegate automatically, and you should not change that relationship. For layers you create yourself, you can assign a delegate
object and use that object to provide the contents of the layer dynamically and perform other tasks. A layer
may also have a layout manager object (assigned to the layoutManager property) to manage the layout of
subviews separately.
Available in OS X v10.5 and later.
155
156
CHAPTER 9. COREANIMATION
9.1.2
Methods
9.1.3
addSublayer(layer as CALayerMBS)
Plugin Version: 13.1, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: Appends the layer
to the layer’s list of sublayers.
Notes: If the array in the sublayers property is nil, calling this method creates an array for that property
and adds the specified layer to it.
9.1.4
available as boolean
Plugin Version: 13.1, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: Returns true if
CALayer is available.
Notes: True on Mac and False on Windows/Linux.
9.1.5
Constructor
Plugin Version: 13.1, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: Initializes the layer.
Notes: Available in OS X v10.5 and later.
9.1.6
display
Plugin Version: 13.1, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: Reloads the content
of this layer.
Notes:
Do not call this method directly. The layer calls this method at appropriate times to update the layer’s content. If the layer has a delegate object, this method attempts to call the delegate’s Configuring the Layer’s
Rendering Behavior method, which the delegate can use to update the layer’s contents. If the delegate does
not implement the Configuring the Layer’s Rendering Behavior method, this method creates a backing store
and calls the layer’s drawInContext: method to fill that backing store with content. The new backing store
replaces the previous contents of the layer.
Subclasses can override this method and use it to set the layer’s contents property directly. You might do
this if your custom layer subclass handles layer updates differently.
9.1. CLASS CALAYERMBS
9.1.7
157
displayIfNeeded
Plugin Version: 13.1, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: Initiates the update
process for a layer if it is currently marked as needing an update.
Notes:
You can call this method as needed to force an update to your layer’s contents outside of the normal update
cycle. Doing so is generally not needed, though. The preferred way to update a layer is to call setNeedsDisplay and let the system update the layer during the next cycle.
Available in OS X v10.6 and later.
9.1.8
layer as CALayerMBS
Plugin Version: 13.1, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: Creates and returns
an instance of the layer object.
Notes:
Returns the initialized layer object or nil if initialization was not successful.
If you subclass CALayer, you may override this method and use it to provide an instance of your specific
subclass.
9.1.9
layoutIfNeeded
Plugin Version: 13.1, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: Recalculate the
receiver’s layout, if required.
Notes: When this message is received, the layer’s super layers are traversed until a ancestor layer is found
that does not require layout. Then layout is performed on the entire layer-tree beneath that ancestor.
9.1.10
layoutSublayers
Plugin Version: 13.1, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: Tells the layer to
update its layout.
Notes:
Subclasses can override this method and use it to implement their own layout algorithm. Your implementation must set the frame of each sublayer managed by the receiver.
The default implementation of this method calls the layoutSublayersOfLayer method of the layer’s delegate
object. If there is no delegate object, or the delegate does not implement that method, this method calls
the layoutSublayersOfLayer method of the object in the layoutManager property.
158
9.1.11
CHAPTER 9. COREANIMATION
removeAllAnimations
Plugin Version: 13.1, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: Remove all animations attached to the layer.
9.1.12
removeFromSuperlayer
Plugin Version: 13.1, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: Detaches the layer
from its parent layer.
Notes:
You can use this method to remove a layer (and all of its sublayers) from a layer hierarchy. This method
updates both the superlayer’s list of sublayers and sets this layer’s superlayer property to nil.
Available in OS X v10.5 and later.
9.1.13
renderInContext(CGContextHandle as Integer) as boolean
Plugin Version: 16.1, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: Renders content of
CALayer into given CGContext.
Notes:
Renders the receiver and its sublayers into the specified context.
This method renders directly from the layer tree, ignoring any animations added to the render tree. Renders
in the coordinate space of the layer.
Returns true if plugin called render command, so layer can draw itself.
Not all layers support drawing into context.
9.1.14
renderInPicture(Pic as Picture) as boolean
Plugin Version: 16.1, Console & Web: No, Mac: Yes, Win: No, Linux: No. Function: Renders content of
CALayer into given Picture.
Notes:
Renders the receiver and its sublayers into the specified context.
This method renders directly from the layer tree, ignoring any animations added to the render tree. Renders
in the coordinate space of the layer.
Returns true if plugin called render command, so layer can draw itself.
Not all layers support drawing into context.
9.1. CLASS CALAYERMBS
9.1.15
159
setNeedsDisplay
Plugin Version: 13.1, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: Marks the layer’s
contents as needing to be updated.
Notes:
Calling this method causes the layer to recache its content. This results in the layer potentially calling either
the displayLayer or drawLayer:inContext method of its delegate. The existing content in the layer’s contents
property is removed to make way for the new content.
Available in OS X v10.5 and later.
9.1.16
setNeedsDisplayInRect(r as CGRectMBS)
Plugin Version: 13.1, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: Marks the region
within the specified rectangle as needing to be updated.
Notes:
r: The rectangular region of the layer to mark as invalid. You must specify this rectangle in the layer’s own
coordinate system.
Available in OS X v10.5 and later.
9.1.17
setNeedsLayout
Plugin Version: 13.1, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: Invalidates the
layer’s layout and marks it as needing an update.
Notes:
You can call this method to indicate that the layout of a layer’s sublayers has changed and must be updated.
The system typically calls this method automatically when the layer’s bounds change or when sublayers are
added or removed. In OS X, if your layer’s layoutManager property contains an object that implements the
invalidateLayoutOfLayer method, that method is called too.
During the next update cycle, the system calls the layoutSublayers method of any layers requiring layout
updates.
Available in OS X v10.5 and later.
9.1.18
sublayers as CALayerMBS()
Plugin Version: 14.0, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: The array with
sublayers.
160
CHAPTER 9. COREANIMATION
9.1.19
Properties
9.1.20
affineTransform as CGAffineTransformMBS
Plugin Version: 13.1, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: The affine version
of the layer’s transform..
Notes:
The affine transform structure that corresponds to the value in the layer’s transform property.
(Read and Write property)
9.1.21
anchorPoint as CGRectMBS
Plugin Version: 13.1, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: Defines the anchor
point of the layer’s bounds rectangle. Animatable.
Notes:
You specify the value for this property using the unit coordinate space. The default value of this property
is (0.5, 0.5), which represents the center of the layer’s bounds rectangle. All geometric manipulations to the
view occur about the specified point. For example, applying a rotation transform to a layer with the default
anchor point causes the layer to rotate around its center. Changing the anchor point to a different location
would cause the layer to rotate around that new point.
For more information about the relationship between the frame, bounds, anchorPoint and position properties, see Core Animation Programming Guide.
Available in OS X v10.5 and later.
(Read and Write property)
9.1.22
anchorPointZ as Double
Plugin Version: 13.1, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: The anchor point
for the layer’s position along the z axis. Animatable.
Notes:
This property specifies the anchor point on the z axis around which geometric manipulations occur. The
point is expressed as a distance (measured in points) along the z axis. The default value of this property is
0.
Available in OS X v10.6 and later.
(Read and Write property)
9.1. CLASS CALAYERMBS
9.1.23
161
AutoresizingMask as Integer
Plugin Version: 13.1, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: A bitmask defining
how the layer is resized when the bounds of its superlayer changes.
Notes:
If your app does not use a layout manager or constraints to handle layout changes, you can assign a value
to this property to adjust the layer’s size in response to changes in the superlayer’s bounds. For a list of
possible values, see ”Autoresizing Mask”.
The default value of this property is kCALayerNotSizable.
(Read and Write property)
9.1.24
backgroundColor as Variant
Plugin Version: 13.1, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: The background
color of the receiver. Animatable.
Notes:
Value must be a CGColorMBS.
The default value of this property is nil.
The value of this property is retained using the Core Foundation retain/release semantics. This behavior
occurs despite the fact that the property declaration appears to use the default assign semantics for object
retention.
(Read and Write property)
9.1.25
borderColor as Variant
Plugin Version: 13.1, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: The color of the
layer’s border. Animatable.
Notes:
Value must be a CGColorMBS.
The default value of this property is an opaque black color.
The value of this property is retained using the Core Foundation retain/release semantics. This behavior
occurs despite the fact that the property declaration appears to use the default assign semantics for object
retention.
(Read and Write property)
162
9.1.26
CHAPTER 9. COREANIMATION
borderWidth as Double
Plugin Version: 13.1, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: The width of the
layer’s border. Animatable.
Notes:
When this value is greater than 0.0, the layer draws a border using the current borderColor value. The
border is drawn inset from the receiver’s bounds by the value specified in this property. It is composited
above the receiver’s contents and sublayers and includes the effects of the cornerRadius property.
The default value of this property is 0.0.
(Read and Write property)
9.1.27
bounds as CGRectMBS
Plugin Version: 13.1, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: The layer’s bounds
rectangle. Animatable.
Notes:
The bounds rectangle is the origin and size of the layer in its own coordinate space. When you create a new
standalone layer, the default value for this property is an empty rectangle, which you must change before
using the layer. The values of each coordinate in the rectangle are measured in points.
For more information about the relationship between the frame, bounds, anchorPoint and position properties, see Core Animation Programming Guide.
(Read and Write property)
9.1.28
className as string
Plugin Version: 14.0, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: The class name of
the layer.
Notes:
Useful for debugging.
(Read only property)
9.1.29
classPath as string
Plugin Version: 14.0, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: The path of this
layer class.
Notes:
9.1. CLASS CALAYERMBS
163
Useful for debugging to know what super classes the layer has.
(Read only property)
9.1.30
contents as Variant
Plugin Version: 15.0, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: The contents of the
layer.
Notes:
Currently only CGImageMBS is allowed.
(Read and Write property)
9.1.31
contentsCenter as CGRectMBS
Plugin Version: 13.1, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: The rectangle that
defines how the layer contents are scaled during a resizing operation. Animatable.
Notes:
You can use this property to subdivide the layer’s content into a 3x3 grid. The value in this property specifies
the location and size of the center rectangle in that grid. If the layer’s contentsGravity property is set to one
of the resizing modes, resizing the layer causes scaling to occur differently in each rectangle of the grid. The
center rectangle is stretched in both dimensions, the top-center and bottom-center rectangles are stretched
only horizontally, the left-center and right-center rectangles are stretched only vertically, and the four corner
rectangles are not stretched at all. Therefore, you can use this technique to implement stretchable backgrounds or images using a three-part or nine-part image.
The value in this property is set to the unit rectangle (0.0,0.0) (1.0,1.0) by default, which causes the entire
image to scale in both dimensions. If you specify a rectangle that extends outside the unit rectangle, the
result is undefined. The rectangle you specify is applied only after the contentsRect property has been
applied to the image.
Note: If the width or height of the rectangle in this property is very small or 0, the value is implicitly changed
to the width or height of a single source pixel centered at the specified location.
(Read and Write property)
9.1.32
contentsRect as CGRectMBS
Plugin Version: 13.1, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: The rectangle, in
the unit coordinate space, that defines the portion of the layer’s contents that should be used. Animatable.
Notes:
Defaults to the unit rectangle (0.0, 0.0, 1.0, 1.0).
164
CHAPTER 9. COREANIMATION
If pixels outside the unit rectangle are requested, the edge pixels of the contents image will be extended
outwards.
If an empty rectangle is provided, the results are undefined.
(Read and Write property)
9.1.33
contentsScale as Double
Plugin Version: 13.1, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: The scale factor
applied to the layer.
Notes:
This value defines the mapping between the logical coordinate space of the layer (measured in points) and
the physical coordinate space (measured in pixels). Higher scale factors indicate that each point in the
layer is represented by more than one pixel at render time. For example, if the scale factor is 2.0 and the
layer’s bounds are 50 x 50 points, the size of the bitmap used to present the layer’s content is 100 x 100 pixels.
The default value of this property is 1.0. For layers attached to a view, the view changes the scale factor automatically to a value that is appropriate for the current screen. For layers you create and manage yourself,
you must set the value of this property yourself based on the resolution of the screen and the content you
are providing. Core Animation uses the value you specify as a cue to determine how to render your content.
Available in OS X v10.7 and later.
(Read and Write property)
9.1.34
cornerRadius as Double
Plugin Version: 13.1, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: The radius to use
when drawing rounded corners for the layer’s background. Animatable.
Notes:
Setting the radius to a value greater than 0.0 causes the layer to begin drawing rounded corners on its
background. By default, the corner radius does not apply to the image in the layer’s contents property; it
applies only to the background color and border of the layer. However, setting the masksToBounds property
to true causes the content to be clipped to the rounded corners.
The default value of this property is 0.0.
(Read and Write property)
9.1. CLASS CALAYERMBS
9.1.35
165
DoubleSided as boolean
Plugin Version: 13.1, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: A Boolean indicating
whether the layer displays its content when facing away from the viewer. Animatable.
Notes:
When the value in this property is false, the layer hides its content when it faces away from the viewer. The
default value of this property is true.
Available in OS X v10.5 and later.
(Read and Write property)
9.1.36
drawsAsynchronously as boolean
Plugin Version: 13.1, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: A Boolean indicating
whether drawing commands are deferred and processed asynchronously in a background thread.
Notes:
When this property is set to true, the graphics context used to draw the layer’s contents queues drawing
commands and executes them on a background thread rather than executing them synchronously. Performing these commands asynchronously can improve performance in some apps. However, you should always
measure the actual performance benefits before enabling this capability.
The default value for this property is false.
Available in OS X v10.8 and later.
(Read and Write property)
9.1.37
frame as CGRectMBS
Plugin Version: 13.1, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: The layer’s frame
rectangle.
Notes:
The frame rectangle is position and size of the layer specified in the superlayer’s coordinate space. For layers,
the frame rectangle is a computed property that is derived from the values in the bounds, anchorPoint and
position properties. When you assign a new value to this property, the layer changes its position and bounds
properties to match the rectangle you specified. The values of each coordinate in the rectangle are measured
in points.
For more information about the relationship between the frame, bounds, anchorPoint and position properties, see Core Animation Programming Guide.
Note: The frame property is not directly animatable. Instead you should animate the appropriate combination of the bounds, anchorPoint and position properties to achieve the desired result.
166
CHAPTER 9. COREANIMATION
(Read and Write property)
9.1.38
Handle as Integer
Plugin Version: 13.1, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: The internal
reference to the layer.
Notes: (Read and Write property)
9.1.39
Hidden as boolean
Plugin Version: 13.1, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: A Boolean indicating
whether the layer is displayed. Animatable.
Notes:
The default value of this property is false.
(Read and Write property)
9.1.40
mask as CALayerMBS
Plugin Version: 15.3, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: The layer to be
used as mask for this layer.
Notes:
A layer whose alpha channel is used as a mask to select between the layer’s background and the result of
compositing the layer’s contents with its filtered background. Defaults to nil. When used as a mask the
layer’s ‘compositingFilter’ and ‘backgroundFilters’ properties are ignored. When setting the mask to a new
layer, the new layer must have a nil superlayer, otherwise the behavior is undefined. Nested masks (mask
layers with their own masks) are unsupported.
(Read and Write property)
9.1.41
masksToBounds as Boolean
Plugin Version: 15.3, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: Whether to mask
by bounds.
Notes:
When true an implicit mask matching the layer bounds is applied to the layer (including the effects of the
‘cornerRadius’ property). If both ‘mask’ and ‘masksToBounds’ are non-nil the two masks are multiplied to
get the actual mask values. Defaults to false. Animatable.
(Read and Write property)
9.1. CLASS CALAYERMBS
9.1.42
167
minificationFilterBias as Double
Plugin Version: 13.1, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: The bias factor
used by the minification filter to determine the levels of detail.
Notes:
This value is used by the minificationFilter when it is set to kCAFilterTrilinear.
The default value of this property is 0.0.
Available in OS X v10.6 and later.
(Read and Write property)
9.1.43
modelLayer as CALayerMBS
Plugin Version: 13.1, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: Returns the model
layer object associated with the receiver, if any.
Notes:
Calling this method on a layer in the presentation tree returns the corresponding layer object in the model
tree. This method returns a value only when a transaction involving changes to the presentation layer is in
progress. If no transaction is in progress, the results of calling this method are undefined.
Available in OS X v10.5 and later.
(Read only property)
9.1.44
needsDisplay as boolean
Plugin Version: 13.1, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: Returns a Boolean
indicating whether the layer has been marked as needing an update.
Notes:
True if the layer needs to be updated.
Available in OS X v10.6 and later.
(Read only property)
9.1.45
needsDisplayOnBoundsChange as boolean
Plugin Version: 13.1, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: A Boolean indicating
whether the layer contents must be updated when its bounds rectangle changes.
Notes:
When this property is set to true, the layer automatically calls its setNeedsDisplay method whenever its
bounds property changes. The default value of this property is false.
168
CHAPTER 9. COREANIMATION
(Read and Write property)
9.1.46
needsLayout as boolean
Plugin Version: 13.1, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: Returns a Boolean
indicating whether the layer has been marked as needing a layout update.
Notes:
True if the layer has been marked as requiring a layout update.
Available in OS X v10.6 and later.
(Read only property)
9.1.47
opacity as Double
Plugin Version: 13.1, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: The opacity of the
receiver. Animatable.
Notes:
The value of this property must be in the range 0.0 (transparent) to 1.0 (opaque). Values outside that range
are clamped to the minimum or maximum. The default value of this property is 1.0.
(Read and Write property)
9.1.48
Opaque as boolean
Plugin Version: 13.1, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: A Boolean value
indicating whether the layer contains completely opaque content.
Notes:
The default value of this property is false. If your app draws completely opaque content that fills the layer’s
bounds, setting this property to true lets the system optimize the rendering behavior for the layer. Specifically, when the layer creates the backing store for your drawing commands, Core Animation omits the alpha
channel of that backing store. Doing so can improve the performance of compositing operations. If you set
the value of this property to true, you must fill the layer’s bounds with opaque content.
Setting this property affects only the backing store managed by Core Animation. If you assign an image
with an alpha channel to the layer’s contents property, that image retains its alpha channel regardless of the
value of this property.
(Read and Write property)
9.1. CLASS CALAYERMBS
9.1.49
169
position as CGRectMBS
Plugin Version: 13.1, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: The layer’s position
in its superlayer’s coordinate space. Animatable.
Notes:
The value of this property is specified in points and is always specified relative to the value in the anchorPoint
property. For new standalone layers, the default position is set to (0.0, 0.0). Changing the frame property
also updates the value in this property.
For more information about the relationship between the frame, bounds, anchorPoint and position properties, see Core Animation Programming Guide.
(Read and Write property)
9.1.50
preferredFrameSize as CGSizeMBS
Plugin Version: 13.1, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: Returns the
preferred size of the layer in the coordinate space of its superlayer.
Notes:
In OS X, the default implementation of this method calls the preferredSizeOfLayer method of its layout
managerthat is, the object in its layoutManager property. If that object does not exist or does not implement that method, this method returns the size of the layer’s current bounds rectangle mapped into the
coordinate space of its superlayer.
(Read only property)
9.1.51
presentationLayer as CALayerMBS
Plugin Version: 13.1, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: Returns a copy of
the presentation layer object that represents the state of the layer as it currently appears onscreen.
Notes:
The layer object returned by this method provides a close approximation of the layer that is currently being
displayed onscreen. While an animation is in progress, you can retrieve this object and use it to get the
current values for those animations.
The sublayers, mask, and superlayer properties of the returned layer return the corresponding objects from
the presentation tree (not the model tree). This pattern also applies to any read-only layer methods. For
example, the hitTest: method of the returned object queries the layer objects in the presentation tree.
Available in OS X v10.5 and later.
(Read only property)
170
9.1.52
CHAPTER 9. COREANIMATION
rasterizationScale as Double
Plugin Version: 15.3, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: The scale at which
the layer will be rasterized.
Notes:
(when the shouldRasterize property has been set to true) relative to the coordinate space of the layer. Defaults to one. Animatable.
(Read and Write property)
9.1.53
shadowColor as Variant
Plugin Version: 15.0, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: The color of the
layers shadow. Animatable.
Notes:
The default value of this property is an opaque black color.
The value of this property is retained using the Core Foundation retain/release semantics. This behavior
occurs despite the fact that the property declaration appears to use the default assign semantics for object
retention.
Value is a CGColorMBS object.
(Read and Write property)
9.1.54
shadowOffset as CGSizeMBS
Plugin Version: 15.0, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: The offset (in
points) of the layers shadow. Animatable.
Notes:
The default value of this property is (0.0, -3.0).
(Read and Write property)
9.1.55
shadowOpacity as Double
Plugin Version: 13.1, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: The opacity of the
layer’s shadow. Animatable.
Notes:
The value in this property must be in the range 0.0 (transparent) to 1.0 (opaque). The default value of this
property is 0.0.
9.1. CLASS CALAYERMBS
171
Available in OS X v10.5 and later.
(Read and Write property)
9.1.56
shadowPath as Variant
Plugin Version: 15.0, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: The shadow path.
Notes:
Value is a CGPathMBS object.
The default value of this property is nil, which causes the layer to use a standard shadow shape. If you
specify a value for this property, the layer creates its shadow using the specified path instead of the layers
composited alpha channel. The path you provide defines the outline of the shadow. It is filled using the
non-zero winding rule and the current shadow color, opacity, and blur radius.
Unlike most animatable properties, this property (as with all CGPathRef animatable properties) does not
support implicit animation. However, the path object may be animated using any of the concrete subclasses
of CAPropertyAnimation. Paths will interpolate as a linear blend of the ”on-line” points; ”off-line” points
may be interpolated non-linearly (to preserve continuity of the curve’s derivative). If the two paths have a
different number of control points or segments, the results are undefined. If the path extends outside the
layer bounds it will not automatically be clipped to the layer, only if the normal layer masking rules cause
that.
Specifying an explicit path usually improves rendering performance.
The value of this property is retained using the Core Foundation retain/release semantics. This behavior
occurs despite the fact that the property declaration appears to use the default assign semantics for object
retention.
(Read and Write property)
9.1.57
shadowRadius as Double
Plugin Version: 15.0, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: The blur radius (in
points) used to render the layers shadow. Animatable.
Notes:
You specify the radius The default value of this property is 3.0.
(Read and Write property)
172
9.1.58
CHAPTER 9. COREANIMATION
shouldRasterize as Boolean
Plugin Version: 15.3, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: Whether view
should raster.
Notes:
When true, the layer is rendered as a bitmap in its local coordinate space (”rasterized”), then the bitmap is
composited into the destination (with the minificationFilter and magnificationFilter properties of the layer
applied if the bitmap needs scaling). Rasterization occurs after the layer’s filters and shadow effects are
applied, but before the opacity modulation. As an implementation detail the rendering engine may attempt
to cache and reuse the bitmap from one frame to the next. (Whether it does or not will have no affect on
the rendered output.) When false the layer is composited directly into the destination whenever possible
(however, certain features of the compositing model may force rasterization, e.g. adding filters). Defaults to
false. Animatable.
(Read and Write property)
9.1.59
superlayer as CALayerMBS
Plugin Version: 13.1, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: The superlayer of
the layer.
Notes:
The superlayer manages the layout of its sublayers.
Available in OS X v10.5 and later.
(Read only property)
9.1.60
zPosition as Double
Plugin Version: 13.1, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: The layer’s position
on the z axis. Animatable.
Notes:
The default value of this property is 0. Changing the value of this property changes the the front-to-back
ordering of layers onscreen. This can affect the visibility of layers whose frame rectangles overlap.
The value of this property is measured in points.
Available in OS X v10.5 and later.
(Read and Write property)
9.1. CLASS CALAYERMBS
9.1.61
Constants
9.1.62
kCALayerBottomEdge = 4
Plugin Version: 13.1. Function: Edge constants for edgeAntialiasingMask property.
Notes: Specifies that the bottom edge of the receiver’s content should be antialiased.
9.1.63
kCALayerHeightSizable = 16
Plugin Version: 13.1. Function: One of the constants for the autoresizingmask property.
Notes: The receiver’s height is flexible.
9.1.64
kCALayerLeftEdge = 1
Plugin Version: 13.1. Function: Edge constants for edgeAntialiasingMask property.
Notes: Specifies that the left edge of the receiver’s content should be antialiased.
9.1.65
kCALayerMaxXMargin = 4
Plugin Version: 13.1. Function: One of the constants for the autoresizingmask property.
Notes: The left margin between the receiver and its superview is flexible.
9.1.66
kCALayerMaxYMargin = 32
Plugin Version: 13.1. Function: One of the constants for the autoresizingmask property.
Notes: The top margin between the receiver and its superview is flexible.
9.1.67
kCALayerMinXMargin = 1
Plugin Version: 13.1. Function: One of the constants for the autoresizingmask property.
Notes: The left margin between the receiver and its superview is flexible.
173
174
9.1.68
CHAPTER 9. COREANIMATION
kCALayerMinYMargin = 8
Plugin Version: 13.1. Function: One of the constants for the autoresizingmask property.
Notes: The top margin between the receiver and its superview is flexible.
9.1.69
kCALayerNotSizable = 0
Plugin Version: 13.1. Function: One of the constants for the autoresizingmask property.
Notes: The receiver cannot be resized.
9.1.70
kCALayerRightEdge = 2
Plugin Version: 13.1. Function: Edge constants for edgeAntialiasingMask property.
Notes: Specifies that the right edge of the receiver’s content should be antialiased.
9.1.71
kCALayerTopEdge = 8
Plugin Version: 13.1. Function: Edge constants for edgeAntialiasingMask property.
Notes: Specifies that the top edge of the receiver’s content should be antialiased.
9.1.72
kCALayerWidthSizable = 2
Plugin Version: 13.1. Function: One of the constants for the autoresizingmask property.
Notes: The receiver’s width is flexible.
9.2. CLASS CATRANSACTIONMBS
9.2
9.2.1
175
class CATransactionMBS
class CATransactionMBS
Plugin Version: 13.1, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: The plugin class for
a CoreAnimation transaction.
Notes:
CATransaction is the Core Animation mechanism for batching multiple layer-tree operations into atomic
updates to the render tree. Every modification to a layer tree must be part of a transaction. Nested transactions are supported.
Core Animation supports two types of transactions: implicit transactions and explicit transactions. Implicit
transactions are created automatically when the layer tree is modified by a thread without an active transaction and are committed automatically when the thread’s run-loop next iterates. Explicit transactions occur
when the the application sends the CATransaction class a begin message before modifying the layer tree,
and a commit message afterwards.
CATransaction allows you to override default animation properties that are set for animatable properties.
You can customize duration, timing function, whether changes to properties trigger animations, and provide
a handler that informs you when all animations from the transaction group are completed.
During a transaction you can temporarily acquire a recursive spin-lock for managing property atomicity.
This is an abstract class. You can’t create an instance, but you can get one from various plugin functions.
9.2.2
Methods
9.2.3
animationDuration as Double
Plugin Version: 13.1, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: Returns the animation duration used by all animations within this transaction group.
9.2.4
available as boolean
Plugin Version: 13.1, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: Returns true if
transaction class is available.
Notes: Returns true on Mac and false on Linux/Windows.
176
9.2.5
CHAPTER 9. COREANIMATION
begin
Plugin Version: 13.1, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: Begin a new
transaction for the current thread.
Notes:
The transaction is nested within the thread’s current transaction, if there is one.
Available in OS X v10.5 and later.
9.2.6
commit
Plugin Version: 13.1, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: Commit all changes
made during the current transaction.
Notes:
Raises an exception if no current transaction exists.
Available in OS X v10.5 and later.
9.2.7
Constructor
Plugin Version: 13.1, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: The private constructor.
9.2.8
flush
Plugin Version: 13.1, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: Flushes any extant
implicit transaction.
Notes:
Delays the commit until any nested explicit transactions have completed.
Flush is typically called automatically at the end of the current runloop, regardless of the runloop mode. If
your application does not have a runloop, you must call this method explicitly.
However, you should attempt to avoid calling flush explicitly. By allowing flush to execute during the runloop
your application will achieve better performance, atomic screen updates will be preserved, and transactions
and animations that work from transaction to transaction will continue to function.
Available in OS X v10.5 and later.
9.2. CLASS CATRANSACTIONMBS
9.2.9
177
kCATransactionAnimationDuration as string
Plugin Version: 13.1, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: One of the keys for
values of a transaction.
Notes:
Duration, in seconds, for animations triggered within the transaction group. The value for this key must be
a number.
Available in OS X v10.5 and later.
9.2.10
kCATransactionDisableActions as string
Plugin Version: 13.1, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: One of the keys for
values of a transaction.
Notes:
If true, implicit actions for property changes made within the transaction group are suppressed. The value
for this key must be a boolean.
Available in OS X v10.5 and later.
9.2.11
setAnimationDuration(value as Double)
Plugin Version: 13.1, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: Sets the animation
duration used by all animations within this transaction group.
Notes: Available in OS X v10.6 and later.
9.2.12
setValue(value as Variant, key as string)
Plugin Version: 13.1, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: Sets the arbitrary
keyed-data for the specified key.
Notes:
value: The value for the key identified by key.
key: The name of one of the receiver’s properties.
Nested transactions have nested data scope; setting a key always sets it in the innermost scope.
Available in OS X v10.5 and later.
178
9.2.13
CHAPTER 9. COREANIMATION
valueForKey(key as string) as Variant
Plugin Version: 13.1, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: Returns the
arbitrary keyed-data specified by the given key.
Notes:
key: The name of one of the receiver’s properties.
Returns the value for the data specified by the key.
Nested transactions have nested data scope. Requesting a value for a key first searches the innermost scope,
then the enclosing transactions.
Available in OS X v10.5 and later.
9.2.14
Properties
9.2.15
Handle as Integer
Plugin Version: 13.1, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: The internal
transaction handle.
Notes: (Read and Write property)
Chapter 10
CoreGraphics
10.1
module CGWindowMBS
10.1.1
module CGWindowMBS
Plugin Version: 11.2, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: This module
contains CoreGraphics functions related to windows.
Example:
// screenshot of all windows on screens
Backdrop = CGWindowMBS.CreateWindowListImage(0, 0, 0, 0, 0, 0, 0)
10.1.2
Methods
10.1.3
CreateWindowList(windowOption as Integer, WindowID as Integer =
0) as UInt32()
Plugin Version: 11.2, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: Returns the list of
window IDs associated with the specified windows in the current user session.
Example:
dim a(-1) as UInt32 = CGWindowMBS.CreateWindowList(0,0)
MsgBox str(UBound(a)+1) + ” windows”
Notes:
179
180
CHAPTER 10. COREGRAPHICS
windowOption: The options describing which window IDs to return. Typical options let you obtain IDs for
all windows or for windows above or below the window specified in the relativeToWindow parameter.
WindowID: The ID of the window to use as a reference point when determining which other windows to
return. For options that do not require a reference window, this parameter can be kCGNullWindowID.
Returns an array of CGWindowID values corresponding to the desired windows. If there are no windows
matching the desired criteria, the function returns an empty array. If you call this function from outside of
a GUI security session or when no window server is running, this function returns nil.
Available in Mac OS X v10.5 and later.
10.1.4
CreateWindowListCGImage(left as Double, top as Double, width as
Double, height as Double, windowOption as Integer, WindowID as Integer = 0, ImageOption as Integer = 0) as Variant
Plugin Version: 11.2, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: Takes a screenshot
from a list of windows.
Notes: Same as CreateWindowListImage, but returns a CGImageMBS. Declared as Variant to reduce plugin interdependencies.
10.1.5
CreateWindowListImage(left as Double, top as Double, width as Double,
height as Double, windowOption as Integer, WindowID as Integer = 0,
ImageOption as Integer = 0) as picture
Plugin Version: 11.2, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: Takes a screenshot
from a list of windows.
Example:
dim p as Picture
// Screenshot of everything:
p = CGWindowMBS.CreateWindowListImage(0, 0, 0, 0, CGWindowMBS.kCGWindowListOptionAll,0,
CGWindowMBS.kCGWindowImageDefault)
// Screenshot of everything behind a window:
p = CGWindowMBS.CreateWindowListImage(0, 0, 0, 0, CGWindowMBS.kCGWindowListOptionOnScreenBelowWindow, CGWindowMBS.GetWindowID(window1), CGWindowMBS.kCGWindowImageDefault)
// Screenshot of everything in front of a window (dock and menubar):
p = CGWindowMBS.CreateWindowListImage(0, 0, 0, 0, CGWindowMBS.kCGWindowListOptionOnScreenAboveWindow, CGWindowMBS.GetWindowID(window1), CGWindowMBS.kCGWindowImageDefault)
10.1. MODULE CGWINDOWMBS
181
// screenshot of a window
p = CGWindowMBS.CreateWindowListImage(0, 0, 0, 0, CGWindowMBS.kCGWindowListOptionIncludingWindow, CGWindowMBS.GetWindowID(window1), CGWindowMBS.kCGWindowImageDefault)
// only shadow of a window (will be in the mask)
p = CGWindowMBS.CreateWindowListImage(0, 0, 0, 0, CGWindowMBS.kCGWindowListOptionIncludingWindow, CGWindowMBS.GetWindowID(window1), CGWindowMBS.kCGWindowImageOnlyShadows)
// desktop decoration is white
p = CGWindowMBS.CreateWindowListImage(0, 0, 0, 0, CGWindowMBS.kCGWindowListExcludeDesktopElements, CGWindowMBS.GetWindowID(window1), CGWindowMBS.kCGWindowImageShouldBeOpaque)
Notes:
Parameters:
left
top
width
height
windowOption
WindowID
ImageOption
Left coordinate rectangle
Top coordinate rectangle
Width of rectangle
Height of rectangle
A combination of kCGWindowListOption* flags
The window ID or 0.
A combination of kCGWindowImage* flags
If you pass a rectangle with all values zero, you select the whole screen.
Returns the screenshot as picture or nil on any error.
Window Options:
kCGWindowListOptionAll
0
kCGWindowListOptionOnScreenOnly
1
kCGWindowListOptionOnScreenAboveWindow
2
kCGWindowListOptionOnScreenBelowWindow
4
kCGWindowListOptionIncludingWindow
8
kCGWindowListExcludeDesktopElements
16
Image Options:
List all windows in this user session, including both on and off-screen windows.
relativeToWindow should be kCGNullWindowID=0.
List all on-screen windows in this user session, ordered from front to back.
relativeToWindow should be kCGNullWindowID=0.
List all on-screen windows above the specified window ordered from front to
back. relativeToWindow should be the window number.
List all on-screen windows below the specified window ordered from front to
back. relativeToWindow should be the window number.
Include the named window in any list, effectively creating ’at-or-above’ or ’ator-below’ lists. relativeToWindow should be the window number.
Exclude any windows from the list that are elements of the desktop, including
the background picture and icons on the desktop.
182
CHAPTER 10. COREGRAPHICS
kCGWindowImageDefault
kCGWindowImageBoundsIgnoreFraming
kCGWindowImageShouldBeOpaque
kCGWindowImageOnlyShadows
10.1.6
0
1
2
4
Default behavior: If a rect of CGRectNull is used bounds computation includes
the framing effects, such as a shadow.
If a rect of CGRectNull is used, ignore framing effects for bounds computation
The captured image should be opaque. Empty areas are white
Capture only shadows.
GetWindowID(w as window) as Integer
Plugin Version: 11.2, Console & Web: No, Mac: Yes, Win: No, Linux: No. Function: Queries the
CoreGraphics Window ID for the given window.
Notes:
Returns 0 on any error.
This ID can be used for CreateWindowListImage.
10.1.7
GetWindowListInfo(windowOption as Integer, WindowID as Integer =
0) as dictionary()
Plugin Version: 11.2, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: Generates and
returns information about the selected windows in the current user session.
Example:
dim a(-1) as Dictionary = CGWindowMBS.GetWindowListInfo(0,0)
dim u as Integer = UBound(a)
if u >10 then u = 10 // show only 10 times
dim lines(-1) as string
for i as Integer = 0 to u
dim d as Dictionary = a(i)
lines.Append d.Value(CGWindowMBS.kCGWindowName)+” of ”+d.Value(CGWindowMBS.kCGWindowOwnerName)
next
// shows 11 windows with names. Not all windows have names.
MsgBox Join(lines, EndOfLine)
Notes:
option: The options describing which window dictionaries to return. Typical options let you return dictionaries for all windows or for windows above or below the window specified in the relativeToWindow parameter.
For more information, see ”Window List Option Constants.”
10.1. MODULE CGWINDOWMBS
183
WindowID: The ID of the window to use as a reference point when determining which other window dictionaries to return. For options that do not require a reference window, this parameter can be 0.
Returns an array of CFDictionaryRef types, each of which contains information about one of the windows
in the current user session. If there are no windows matching the desired criteria, the function returns an
empty array. If you call this function from outside of a GUI security session or when no window server is
running, this function returns nil.
You can use this function to get detailed information about the configuration of one or more windows in the
current user session. For example, you can use this function to get the bounds of the window, its window
ID, and information about how it is managed by the window server. For the list of keys and values that may
be present in the dictionary, see kCGWindow* constants.
Generating the dictionaries for system windows is a relatively expensive operation. As always, you should
profile your code and adjust your usage of this function appropriately for your needs.
Available in Mac OS X v10.5 and later.
10.1.8
Constants
10.1.9
kCGBackingStoreBuffered = 2
Plugin Version: 11.2. Function: One of the backing store constants.
10.1.10
kCGBackingStoreNonretained = 1
Plugin Version: 11.2. Function: One of the backing store constants.
10.1.11
kCGBackingStoreRetained = 0
Plugin Version: 11.2. Function: One of the backing store constants.
10.1.12
kCGNullWindowID = 0
Plugin Version: 11.2. Function: The number for an invalid window ID.
184
CHAPTER 10. COREGRAPHICS
10.1.13
kCGWindowAlpha = ”kCGWindowAlpha”
Plugin Version: 11.2. Function: One of the possible keys in the window info dictionary.
Notes: The alpha fade of the window. The value of this key is a floating-point value. The value 1.0 is
normal (opaque); the value 0.0 is fully transparent (invisible).
10.1.14
kCGWindowBackingLocationVideoMemory = ”kCGWindowBackingLocationVideoMemory”
Plugin Version: 11.2. Function: One of the possible keys in the window info dictionary.
Notes: Optional. If present, true if the window backing store is in video memory, false otherwise. If the
key is not present, then the window backing store is in main memory. The value of this key is a Boolean.
10.1.15
kCGWindowBounds = ”kCGWindowBounds”
Plugin Version: 11.2. Function: One of the possible keys in the window info dictionary.
Example:
dim a(-1) as Dictionary = CGWindowMBS.GetWindowListInfo(CGWindowMBS.kCGWindowListOptionOnScreenOnly,0)
//cycle thru window names and get window size
for each d as Dictionary in a
dim windowname as string = d.Lookup(CGWindowMBS.kCGWindowName, ””)
if Instr(1,windowname,”Play”) >0 then
dim bounds as Dictionary = d.Lookup(CGWindowMBS.kCGWindowBounds,nil)
dim
dim
dim
dim
x as Integer = bounds.Lookup(”X”, 0)
y as Integer = bounds.Lookup(”Y”, 0)
w as Integer = bounds.Lookup(”Width”, 0)
h as Integer = bounds.Lookup(”Height”, 0)
MsgBox ”Found window at ”+str(x)+”/”+str(y)+” with size ”+str(w)+”/”+str(h)
end if
next
Notes: The bounds of the window in screen space, with the origin at the upper-left corner of the main
display. The value of this key is a Dictionary.
10.1. MODULE CGWINDOWMBS
10.1.16
185
kCGWindowImageBoundsIgnoreFraming = 1
Plugin Version: 11.2. Function: One of the image options constants.
Notes: If null rect is passed as the screen bounds, then then bounds computation excludes window frame
ornamentation, such as a shadow.
10.1.17
kCGWindowImageDefault = 0
Plugin Version: 11.2. Function: One of the image options constants.
Notes: If null rectangle is passed as the screen bounds, then then bounds computation includes window
frame ornamentation, such as a shadow.
10.1.18
kCGWindowImageOnlyShadows = 4
Plugin Version: 11.2. Function: One of the image options constants.
Notes: Only draw the windows’ shadows, not the windows themselves.
10.1.19
kCGWindowImageShouldBeOpaque = 2
Plugin Version: 11.2. Function: One of the image options constants.
Notes: Force the created image to be opaque. Empty areas are white.
10.1.20
kCGWindowIsOnscreen = ”kCGWindowIsOnscreen”
Plugin Version: 11.2. Function: One of the possible keys in the window info dictionary.
Notes: Optional. If present, true if the window is ordered on screen, false otherwise. If the key is not
present, then the window is not ordered on screen. The value of this key is a boolean.
10.1.21
kCGWindowLayer = ”kCGWindowLayer”
Plugin Version: 11.2. Function: One of the possible keys in the window info dictionary.
Notes: The window layer number of the window. The value of this key is a 32-bit signed integer value.
186
10.1.22
CHAPTER 10. COREGRAPHICS
kCGWindowListExcludeDesktopElements = 16
Plugin Version: 11.2. Function: One of the window list option constants.
Notes: Exclude any windows from the list that are elements of the desktop.
10.1.23
kCGWindowListOptionAll = 0
Plugin Version: 11.2. Function: One of the window list option constants.
Notes: List all windows in this user session, including both on- and off-screen windows. The parameter
WindowID should be kCGNullWindowID.
10.1.24
kCGWindowListOptionIncludingWindow = 8
Plugin Version: 11.2. Function: One of the window list option constants.
Notes: Include the window specified by WindowID in any list, effectively creating ’at-or-above’ or ’at-orbelow’ lists.
10.1.25
kCGWindowListOptionOnScreenAboveWindow = 2
Plugin Version: 11.2. Function: One of the window list option constants.
Notes: List all on-screen windows above the window specified by WindowID, ordered from front to back.
10.1.26
kCGWindowListOptionOnScreenBelowWindow = 4
Plugin Version: 11.2. Function: One of the window list option constants.
Notes: List all on-screen windows below the window specified by WindowID, ordered from front to back.
10.1.27
kCGWindowListOptionOnScreenOnly = 1
Plugin Version: 11.2. Function: One of the window list option constants.
Notes: List all on-screen windows in this user session, ordered from front to back. The parameter WindowID should be kCGNullWindowID.
10.1. MODULE CGWINDOWMBS
10.1.28
187
kCGWindowMemoryUsage = ”kCGWindowMemoryUsage”
Plugin Version: 11.2. Function: One of the possible keys in the window info dictionary.
Notes: An estimate of the memory in bytes currently used by the window and its supporting data structures. The value of this key is a 64-bit signed integer value.
10.1.29
kCGWindowName = ”kCGWindowName”
Plugin Version: 11.2. Function: One of the possible keys in the window info dictionary.
Example:
// find window with containing ”Play” in name.
dim a(-1) as Dictionary = CGWindowMBS.GetWindowListInfo(CGWindowMBS.kCGWindowListOptionOnScreenOnly, 0)
for each d as Dictionary in a
dim windowname as string = d.Lookup(CGWindowMBS.kCGWindowName, ””)
if Instr(1,windowname,”Play”) >0 then
msgBox ”I found it and the ID is ”+d.Lookup(CGWindowMBS.kCGWindowNumber, ””)
end if
next
Notes: Optional. If present, the name of the window. The value of this key is a string.
10.1.30
kCGWindowNumber = ”kCGWindowNumber”
Plugin Version: 11.2. Function: One of the possible keys in the window info dictionary.
Example:
// find window with containing ”Play” in name.
dim a(-1) as Dictionary = CGWindowMBS.GetWindowListInfo(CGWindowMBS.kCGWindowListOptionOnScreenOnly, 0)
for each d as Dictionary in a
dim windowname as string = d.Lookup(CGWindowMBS.kCGWindowName, ””)
if Instr(1,windowname,”Play”) >0 then
msgBox ”I found it and the ID is ”+d.Lookup(CGWindowMBS.kCGWindowNumber, ””)
end if
next
Notes: The window ID, a unique value within the user session representing the window. The value of this
188
CHAPTER 10. COREGRAPHICS
key is a 32-bit signed integer value.
10.1.31
kCGWindowOwnerName = ”kCGWindowOwnerName”
Plugin Version: 11.2. Function: One of the possible keys in the window info dictionary.
Notes: Optional. If present, the name of the application process which owns the window. The value of this
key is a string.
10.1.32
kCGWindowOwnerPID = ”kCGWindowOwnerPID”
Plugin Version: 11.2. Function: One of the possible keys in the window info dictionary.
Notes: The process ID of the process that owns the window. The value of this key is a 32-bit signed integer
value.
10.1.33
kCGWindowSharingNone = 0
Plugin Version: 11.2. Function: One of the sharing state constants.
Notes: No sharing.
10.1.34
kCGWindowSharingReadOnly = 1
Plugin Version: 11.2. Function: One of the sharing state constants.
Notes: Read only.
10.1.35
kCGWindowSharingReadWrite = 2
Plugin Version: 11.2. Function: One of the sharing state constants.
Notes: Read and Write
10.1.36
kCGWindowSharingState = ”kCGWindowSharingState”
Plugin Version: 11.2. Function: One of the possible keys in the window info dictionary.
Notes: The sharing state of the window, one of kCGWindowSharingNone, kCGWindowSharingReadOnly,
or kCGWindowSharingReadWrite. The value of this key is a 32-bit signed integer value.
10.1. MODULE CGWINDOWMBS
10.1.37
189
kCGWindowStoreType = ”kCGWindowStoreType”
Plugin Version: 11.2. Function: One of the possible keys in the window info dictionary.
Notes: The backing store type of the window, one of kCGBackingStoreRetained, kCGBackingStoreNonretained, or kCGBackingStoreBuffered. The value of this key is a 32-bit signed integer value.
10.1.38
kCGWindowWorkspace = ”kCGWindowWorkspace”
Plugin Version: 11.2. Function: One of the possible keys in the window info dictionary.
Notes: Optional. If present, the workspace ID of the workspace associated with the window. The value of
this key is a 32-bit signed integer value.
190
CHAPTER 10. COREGRAPHICS
Chapter 11
Files
11.1
class Folderitem
11.1.1
class Folderitem
Console & Web: Yes, Mac: Yes, Win: Yes, Linux: Yes. Function: One of Realbasic’s base classes.
Notes: Handles access to files.
11.1.2
Methods
11.1.3
BackupIsItemExcludedMBS(byref excludeByPath as boolean) as boolean
Plugin Version: 7.7, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: Report whether or
not an item is being excluded from backup.
Notes:
excludeByPath: pass a boolean variable to determine whether or not the given item is excluded as an absolute path or whether it is sticky to the item.
Returns true if the item or any of its ancestors are excluded from backup, false otherwise.
Require Mac OS X 10.5.
191
192
11.1.4
CHAPTER 11. FILES
BackupSetItemExcludedMBS(exclude as boolean, excludeByPath as boolean)
as Integer
Plugin Version: 7.7, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: Add or remove an
item from the list of items excluded from backup.
Notes:
When backing up, the backup daemon skips items marked by this call. If a folder is marked for exclusion,
it and its contents are excluded from backup. When specifying by path, it is OK to pass a URL of an
item/folder that does not exist yet.
Returns the error code. -1 is the error code in case the function is not available.
Require Mac OS X 10.5.
11.1.5
QuickLookMBS(MaxWidth as Integer = 500, MaxHeight as Integer =
500, IconMode as Boolean = false, ScaleFactor as Double = 1.0) as
picture
Plugin Version: 7.7, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: Creates a thumbnail
for the designated file.
Example:
dim f as FolderItem
f=SpecialFolder.Desktop.Child(”test.jpg”)
// shows the icon in 128x128 scaled by factor 4:
Backdrop=f.QuickLookMBS(128,128,true,4)
// shows the icon in default size:
Backdrop=f.QuickLookMBS(128,128,true,0)
// shows preview of image in 128x128 pixels.
Backdrop=f.QuickLookMBS(128,128,false,0)
// shows preview of image in 512x512 pixels.
Backdrop=f.QuickLookMBS(128,128,false,4)
// shows preview of image in 512x512 pixels.
Backdrop=f.QuickLookMBS(512,512,false,0)
// use Icon function in case no preview is available:
Backdrop=f.iconmbs(512)
11.1. CLASS FOLDERITEM
193
Notes:
Returns nil if Quick Look does not support this file type. In that case you may use folderitem.Icon() with
the given size.
MaxWidth and MacHeight specify the maximum desired size.
If ScaleFactor is bigger than zero, it is used. Else the default value is used.
If IconMode is true, QL will produce an icon (ie a thumbnail and all the icon decor, like shadows, curled
corner, etc.).
If you look for a control to show quicklook preview like the finder, please check the QLPreviewPanelMBS
window and the QLPreviewViewMBS control.
QuickLook does not provide images for items in special folders like temporary folders.
11.1.6
QuickLookMTMBS(MaxWidth as Integer = 500, MaxHeight as Integer
= 500, IconMode as Boolean = false, ScaleFactor as Double = 1.0) as
picture
Plugin Version: 13.2, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: Creates a thumbnail
for the designated file.
Notes:
Same as QuickLookMBS, but thread friendly.
Must be called inside a Xojo (Real Studio) thread so time yields to main thread and you can keep the GUI
running.
QuickLook does not provide images for items in special folders like temporary folders.
11.1.7
Properties
11.1.8
BackupItemExcludedMBS as boolean
Plugin Version: 7.7, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: Whether or not an
item is being excluded from backup.
Notes:
This is the easy method to just query whether a file is marked as being excluded from backup. You can
assign a boolean value to exclude (true) or include (false) the file.
194
CHAPTER 11. FILES
Require Mac OS X 10.5. Returns false on all other operation systems.
(Read and Write computed property)
11.1.9
MacQuarantinePropertiesMBS as MacQuarantinePropertiesMBS
Plugin Version: 9.8, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: Gets or sets the
quarantine options for a file.
Example:
dim f as FolderItem = SpecialFolder.Desktop.Child(”test.app”)
// read value
dim q as MacQuarantinePropertiesMBS = f.MacQuarantinePropertiesMBS
MsgBox q.AgentName
// set value
q = new MacQuarantinePropertiesMBS
q.AgentBundleIdentifier = ”test.test”
q.AgentName = ”testing app”
q.DataURL=”http://www.monkeybreadsoftware.de/test.dmg”
q.OriginURL=”http://www.monkeybreadsoftware.de/”
q.Type=q.kTypeWebDownload
f.MacQuarantinePropertiesMBS = q
// clear
f.MacQuarantinePropertiesMBS = nil
Notes:
Requires Mac OS X 10.5.
(Read and Write computed property)
11.2. CLASS MACQUARANTINEPROPERTIESMBS
11.2
class MacQuarantinePropertiesMBS
11.2.1
class MacQuarantinePropertiesMBS
195
Plugin Version: 9.8, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: The class for
quarantine options.
Example:
dim f as FolderItem = SpecialFolder.Desktop.Child(”test.app”)
// read value
dim q as MacQuarantinePropertiesMBS = f.MacQuarantinePropertiesMBS
MsgBox q.AgentName
// set value
q = new MacQuarantinePropertiesMBS
q.AgentBundleIdentifier = ”test.test”
q.AgentName = ”testing app”
q.DataURL=”http://www.monkeybreadsoftware.de/test.dmg”
q.OriginURL=”http://www.monkeybreadsoftware.de/”
q.Type=q.kTypeWebDownload
f.MacQuarantinePropertiesMBS = q
// clear
f.MacQuarantinePropertiesMBS = nil
Notes: Requires Mac OS X 10.5.
11.2.2
Properties
11.2.3
AgentBundleIdentifier as String
Plugin Version: 9.8, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: The bundle identifier
of the quarantining agent, if available.
Example:
dim f as FolderItem = SpecialFolder.Desktop.Child(”test.app”)
dim q as MacQuarantinePropertiesMBS = f.MacQuarantinePropertiesMBS
MsgBox q.AgentBundleIdentifier
196
CHAPTER 11. FILES
Notes:
When setting quarantine properties, this value is set automatically if the it is undefined. The automatic
value is the main bundle identifier of the current process.
(Read and Write property)
11.2.4
AgentName as String
Plugin Version: 9.8, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: The name of the
quarantining agent (application or program).
Example:
dim f as FolderItem = SpecialFolder.Desktop.Child(”test.app”)
dim q as MacQuarantinePropertiesMBS = f.MacQuarantinePropertiesMBS
MsgBox q.AgentName
Notes:
When setting quarantine properties, this value is set automatically to the current process name if this value
is not defined.
(Read and Write property)
11.2.5
DataURL as String
Plugin Version: 9.8, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: The URL from which
the data for the quarantined item data was actaully streamed or downloaded, if available.
Notes:
dim f as FolderItem = SpecialFolder.Desktop.Child(”test.app”)
dim q as MacQuarantinePropertiesMBS = f.MacQuarantinePropertiesMBS
MsgBox q.DataURL
(Read and Write property)
11.2.6
Dic as Variant
Plugin Version: 12.4, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: The original
dictionary from Mac OS X.
Notes:
This is a CFDictionaryMBS object which we provide for debugging.
You can pass it to CFShowMBS to print on console.
(Read and Write property)
11.2. CLASS MACQUARANTINEPROPERTIESMBS
11.2.7
197
OriginURL as String
Plugin Version: 9.8, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: The URL of the
resource originally hosting the quarantined item, from the user’s point of view.
Example:
dim f as FolderItem = SpecialFolder.Desktop.Child(”test.app”)
dim q as MacQuarantinePropertiesMBS = f.MacQuarantinePropertiesMBS
MsgBox q.OriginURL
Notes:
For web downloads, this property is the URL of the web page on which the user initiated the download. For
attachments, this property is the URL of the resource to which the quarantined item was attached (e.g. the
email message, calendar event, etc.). The origin URL may be a file URL for local resources, or a custom URL
to which the quarantining application will respond when asked to open it. The quarantining application
should respond by displaying the resource to the user. Note: The origin URL should not be set to the data
URL, or the quarantining application may start downloading the file again if the user choses to view the
origin URL while resolving a quarantine warning.
(Read and Write property)
11.2.8
TimeStamp as Date
Plugin Version: 9.8, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: The date and time
the item was quarantined.
Example:
dim f as FolderItem = SpecialFolder.Desktop.Child(”test.app”)
dim q as MacQuarantinePropertiesMBS = f.MacQuarantinePropertiesMBS
MsgBox q.TimeStamp.LongDate+” ”+q.TimeStamp.LongTime
Notes:
When setting quarantine properties, this property is set automatically to the current date and time if this
value is not set.
(Read and Write property)
198
11.2.9
CHAPTER 11. FILES
Type as String
Plugin Version: 9.8, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: A symbolic string
identifying the why the item is quarantined, if available.
Example:
dim f as FolderItem = SpecialFolder.Desktop.Child(”test.app”)
dim q as MacQuarantinePropertiesMBS = f.MacQuarantinePropertiesMBS
MsgBox q.Type
Notes: (Read and Write property)
11.2.10
Constants
11.2.11
kTypeCalendarEventAttachment = ”LSQuarantineTypeCalendarEventAttachment”
Plugin Version: 9.8. Function: One of the type constants.
11.2.12
kTypeEmailAttachment = ”LSQuarantineTypeEmailAttachment”
Plugin Version: 9.8. Function: One of the type constants.
11.2.13
kTypeInstantMessageAttachment = ”LSQuarantineTypeInstantMessageAttachment”
Plugin Version: 9.8. Function: One of the type constants.
11.2.14
kTypeOtherAttachment = ”LSQuarantineTypeOtherAttachment”
Plugin Version: 9.8. Function: One of the type constants.
11.2.15
kTypeOtherDownload = ”LSQuarantineTypeOtherDownload”
Plugin Version: 9.8. Function: One of the type constants.
11.2. CLASS MACQUARANTINEPROPERTIESMBS
11.2.16
kTypeWebDownload = ”LSQuarantineTypeWebDownload”
Plugin Version: 9.8. Function: One of the type constants.
199
200
CHAPTER 11. FILES
Chapter 12
Folder Change Watching
12.1
class FSEventsMBS
12.1.1
class FSEventsMBS
Plugin Version: 8.1, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: A class for the Mac
OS X 10.5 feature called FSEvents which can be used to monitor a folder hierarchie for changes.
Notes:
The text below is from the Apple documentation (With some plugin related modifications). The plugin does
currently not support the device related functions, but that can be added later if you need it.
This class provides a mechanism to notify clients about directories they ought to re-scan in order to keep
their internal data structures up-to-date with respect to the true state of the file system. (For example,
when files or directories are created, modified, or removed.) It sends these notifications ”in bulk”, possibly
notifying the client of changes to several directories in a single callback. By using the API, clients can notice
such changes quickly, without needing to resort to recursive polling/scanning of the file system.
Much like kqueues, the FSEvents API allows an application to find near-immediately when the contents of
a particular directory has changed. However, unlike kqueues, the FSEvents API allows the application to
monitor the whole file system hierarchy rooted at a specified directory (and still get precise per-directory
notifications) – to do this with the kqueues API would require the client to monitor each directory individually.
Clients can register interest in a chunk of the filesystem hierarchy and will receive callbacks from their runloop
whenever an event occurs that modifies the filesystem therein. The callback will indicate the exact directory
in which the event occurred, so the client only has to scan that directory for updated info, not all its children.
Clients can supply a ”latency” parameter that tells how long to wait after an event occurs before forwarding
it; this reduces the volume of events and reduces the chance that the client will see an ”intermediate” state,
like those that arise when doing a ”safe save” of a file, creating a package, or downloading a file via Safari.
201
202
CHAPTER 12. FOLDER CHANGE WATCHING
The lifecycle of an FSEventStream consists of these stages:
1. new FSEventsMBS(...) ->Creates an FSEventStream.
2. Start() ->Starts receiving events and servicing them from the client’s runloop(s) using the callback supplied by the client when the stream was created. If a value was supplied for the sinceWhen parameter
then ”historical” events will be sent via your callback first, then a HistoryDone event, then ”contemporary”
events will be sent on an ongoing basis (as though you had supplied kFSEventStreamEventIdSinceNow for
sinceWhen).
3. Stop() ->Stops the stream, ensuring the client’s callback will not be called again for this stream. After
stopping the stream, it can be restarted seamlessly via Start() without missing any events.
Once the event stream has been started, the following calls can be used:
GetLatestEventId() ->Initially, this returns the sinceWhen value supplied when the stream was created;
thereafter, it is updated with the highest-numbered event ID mentioned in the current batch of events just
before invoking the client’s callback. Clients can store this value persistently as long as they also store the
UUID for the device (obtained via CopyUUIDForDevice()). Clients can then later supply this event ID as
the sinceWhen parameter to CreateRelativeToDevice(), as long as its UUID matches what you stored. This
works because the FSEvents service stores events in a persistent, per-volume database. In this regard,the
stream of event IDs acts like a global, system-wide clock, but bears no relation to any particular timebase.
FlushAsync() ->Requests that the fseventsd daemon send any events it has already buffered (via the latency
parameter to one of the constructors). This occurs asynchronously; clients will not have received all the
callbacks by the time this call returns to them.
FlushSync() ->Requests that the fseventsd daemon send any events it has already buffered (via the latency
parameter to one of the constructors). Then runs the runloop in its private mode till all events that have
occurred have been reported (via the clients callback). This occurs synchronously; clients will have received
all the callbacks by the time this call returns to them.
GetDeviceBeingWatched() ->Gets the dev t value supplied when the stream was created with CreateRelativeToDevice(), otherwise 0.
CopyPathsBeingWatched() ->Gets the paths supplied when the stream was created with one of the constructors.
Calls that can be made without a stream:
12.1. CLASS FSEVENTSMBS
203
CopyUUIDForDevice() ->Gets a UUID that uniquely identifies the FSEvents database for that volume. If
the database gets discarded then its replacement will have a different UUID so that clients will be able to
detect this situation and avoid trying to use event IDs that they stored as the sinceWhen parameter to the
FSEventStreamCreate...() functions.
GetCurrentEventId() ->Gets the most recently generated event ID, system-wide (not just for one stream).
GetLastEventIdForDeviceBeforeTime() ->Gets the last event ID for the given device that was returned before the given time. This is conservative in the sense that if you then use the returned event ID as the
sinceWhen parameter of CreateRelativeToDevice() that you will not miss any events that happened since
that time. On the other hand, you might receive some (harmless) extra events.
PurgeEventsForDeviceUpToEventId() ->Purges old events from the persistent per-volume database maintained by the service. You can combine this with GetLastEventIdForDeviceBeforeTime(). Can only be
called by the root user.
For Windows, you can use WindowsDirectoryWatcherMBS class.
12.1.2
Methods
12.1.3
Available as Boolean
Plugin Version: 8.1, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: Whether the FSEvent
functions are working.
Example:
if FSEventsMBS.Available then
MsgBox ”available”
else
MsgBox ”not available”
end if
Notes: True on Mac OS X 10.5 and false on other versions and operation systems.
12.1.4
Constructor(DeviceToWatch as Integer, path as string, sinceWhen as
UInt64, latency as Double, flags as Integer)
Plugin Version: 8.4, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: Creates a new FS
event stream object for a particular device with the given parameters.
Notes:
204
CHAPTER 12. FOLDER CHANGE WATCHING
In order to start receiving callbacks you must also call Start().
deviceToWatch:
A dev t corresponding to the device which you want to receive notifications from. Use GetDeviceID to get
such a device ID.
pathsToWatchRelativeToDevice:
A string, specifying a relative path to a directory on the device identified by the dev parameter. The
path should be relative to the root of the device. For example, if a volume ”MyData” is mounted at
”/Volumes/MyData” and you want to watch ”/Volumes/MyData/Pictures/July”, specify a path string of
”Pictures/July”. To watch the root of a volume pass a path of ”” (the empty string).
sinceWhen:
The service will supply events that have happened after the given event ID. To ask for events ”since now”
pass the constant kFSEventStreamEventIdSinceNow. Often, clients will supply the highest-numbered FSEventStreamEventId they have received in a callback, which they can obtain via the GetLatestEventId() accessor. Do not pass zero for sinceWhen, unless you want to receive events for every directory modified since
”the beginning of time” – an unlikely scenario.
latency:
The number of seconds the service should wait after hearing about an event from the kernel before passing
it along to the client via its event. Specifying a larger value may result in more effective temporal coalescing,
resulting in fewer callbacks.
flags:
Flags that modify the behavior of the stream being created.
On success the handle property is not 0.
See also:
• 12.1.5 Constructor(DeviceToWatch as Integer, paths() as string, sinceWhen as UInt64, latency as
Double, flags as Integer)
205
• 12.1.6 Constructor(path as folderitem, sinceWhen as UInt64, latency as Double, flags as Integer) 205
• 12.1.7 Constructor(path as string, sinceWhen as UInt64, latency as Double, flags as Integer)
206
• 12.1.8 Constructor(paths() as folderitem, sinceWhen as UInt64, latency as Double, flags as Integer)
207
• 12.1.9 Constructor(paths() as string, sinceWhen as UInt64, latency as Double, flags as Integer)
207
12.1. CLASS FSEVENTSMBS
12.1.5
205
Constructor(DeviceToWatch as Integer, paths() as string, sinceWhen as
UInt64, latency as Double, flags as Integer)
Plugin Version: 8.4, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: Creates a new FS
event stream object with the given parameters.
Notes:
In order to start receiving callbacks you must also call Start.
paths: The folders you want to watch. (more exactly the root folders of the folder hierarchies you want to
watch)
sinceWhen: The service will supply events that have happened after the given event ID. To ask for events
”since now” pass the constant kFSEventStreamEventIdSinceNow. Often, clients will supply the highestnumbered FSEventStreamEventId they have received in a callback, which they can obtain via the GetLatestEventId() accessor. Do not pass zero for sinceWhen, unless you want to receive events for every directory
modified since ”the beginning of time” – an unlikely scenario.
latency: The number of seconds the service should wait after hearing about an event from the kernel before
passing it along to the client via its callback. Specifying a larger value may result in more effective temporal
coalescing, resulting in fewer callbacks and greater overall efficiency.
flags: Flags that modify the behavior of the stream being created.
See also:
• 12.1.4 Constructor(DeviceToWatch as Integer, path as string, sinceWhen as UInt64, latency as Double,
flags as Integer)
203
• 12.1.6 Constructor(path as folderitem, sinceWhen as UInt64, latency as Double, flags as Integer) 205
• 12.1.7 Constructor(path as string, sinceWhen as UInt64, latency as Double, flags as Integer)
206
• 12.1.8 Constructor(paths() as folderitem, sinceWhen as UInt64, latency as Double, flags as Integer)
207
• 12.1.9 Constructor(paths() as string, sinceWhen as UInt64, latency as Double, flags as Integer)
12.1.6
207
Constructor(path as folderitem, sinceWhen as UInt64, latency as Double, flags as Integer)
Plugin Version: 8.1, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: Creates a new FS
event stream object with the given parameters.
Notes:
In order to start receiving callbacks you must also call Start.
path: The folder you want to watch. (more exactly the root folder of the folder hierarchie you want to
watch)
sinceWhen: The service will supply events that have happened after the given event ID. To ask for events
206
CHAPTER 12. FOLDER CHANGE WATCHING
”since now” pass the constant kFSEventStreamEventIdSinceNow. Often, clients will supply the highestnumbered FSEventStreamEventId they have received in a callback, which they can obtain via the GetLatestEventId() accessor. Do not pass zero for sinceWhen, unless you want to receive events for every directory
modified since ”the beginning of time” – an unlikely scenario.
latency: The number of seconds the service should wait after hearing about an event from the kernel before
passing it along to the client via its callback. Specifying a larger value may result in more effective temporal
coalescing, resulting in fewer callbacks and greater overall efficiency.
flags: Flags that modify the behavior of the stream being created.
See also:
• 12.1.4 Constructor(DeviceToWatch as Integer, path as string, sinceWhen as UInt64, latency as Double,
flags as Integer)
203
• 12.1.5 Constructor(DeviceToWatch as Integer, paths() as string, sinceWhen as UInt64, latency as
Double, flags as Integer)
205
• 12.1.7 Constructor(path as string, sinceWhen as UInt64, latency as Double, flags as Integer)
206
• 12.1.8 Constructor(paths() as folderitem, sinceWhen as UInt64, latency as Double, flags as Integer)
207
• 12.1.9 Constructor(paths() as string, sinceWhen as UInt64, latency as Double, flags as Integer)
12.1.7
207
Constructor(path as string, sinceWhen as UInt64, latency as Double,
flags as Integer)
Plugin Version: 8.4, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: Creates a new FS
event stream object with the given parameters.
Notes:
In order to start receiving callbacks you must also call Start.
path: The folder you want to watch. (more exactly the root folder of the folder hierarchie you want to
watch)
sinceWhen: The service will supply events that have happened after the given event ID. To ask for events
”since now” pass the constant kFSEventStreamEventIdSinceNow. Often, clients will supply the highestnumbered FSEventStreamEventId they have received in a callback, which they can obtain via the GetLatestEventId() accessor. Do not pass zero for sinceWhen, unless you want to receive events for every directory
modified since ”the beginning of time” – an unlikely scenario.
latency: The number of seconds the service should wait after hearing about an event from the kernel before
passing it along to the client via its callback. Specifying a larger value may result in more effective temporal
coalescing, resulting in fewer callbacks and greater overall efficiency.
flags: Flags that modify the behavior of the stream being created.
See also:
• 12.1.4 Constructor(DeviceToWatch as Integer, path as string, sinceWhen as UInt64, latency as Double,
flags as Integer)
203
12.1. CLASS FSEVENTSMBS
207
• 12.1.5 Constructor(DeviceToWatch as Integer, paths() as string, sinceWhen as UInt64, latency as
Double, flags as Integer)
205
• 12.1.6 Constructor(path as folderitem, sinceWhen as UInt64, latency as Double, flags as Integer) 205
• 12.1.8 Constructor(paths() as folderitem, sinceWhen as UInt64, latency as Double, flags as Integer)
207
• 12.1.9 Constructor(paths() as string, sinceWhen as UInt64, latency as Double, flags as Integer)
12.1.8
207
Constructor(paths() as folderitem, sinceWhen as UInt64, latency as
Double, flags as Integer)
Plugin Version: 8.1, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: Creates a new FS
event stream object with the given parameters.
Notes:
In order to start receiving callbacks you must also call Start.
paths: The folders you want to watch. (more exactly the root folders of the folder hierarchies you want to
watch)
sinceWhen: The service will supply events that have happened after the given event ID. To ask for events
”since now” pass the constant kFSEventStreamEventIdSinceNow. Often, clients will supply the highestnumbered FSEventStreamEventId they have received in a callback, which they can obtain via the GetLatestEventId() accessor. Do not pass zero for sinceWhen, unless you want to receive events for every directory
modified since ”the beginning of time” – an unlikely scenario.
latency: The number of seconds the service should wait after hearing about an event from the kernel before
passing it along to the client via its callback. Specifying a larger value may result in more effective temporal
coalescing, resulting in fewer callbacks and greater overall efficiency.
flags: Flags that modify the behavior of the stream being created.
See also:
• 12.1.4 Constructor(DeviceToWatch as Integer, path as string, sinceWhen as UInt64, latency as Double,
flags as Integer)
203
• 12.1.5 Constructor(DeviceToWatch as Integer, paths() as string, sinceWhen as UInt64, latency as
Double, flags as Integer)
205
• 12.1.6 Constructor(path as folderitem, sinceWhen as UInt64, latency as Double, flags as Integer) 205
• 12.1.7 Constructor(path as string, sinceWhen as UInt64, latency as Double, flags as Integer)
206
• 12.1.9 Constructor(paths() as string, sinceWhen as UInt64, latency as Double, flags as Integer)
207
12.1.9
Constructor(paths() as string, sinceWhen as UInt64, latency as Double,
flags as Integer)
Plugin Version: 8.4, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: Creates a new FS
event stream object for a particular device with the given parameters.
208
CHAPTER 12. FOLDER CHANGE WATCHING
Notes:
In order to start receiving callbacks you must also call Start().
deviceToWatch:
A dev t corresponding to the device which you want to receive notifications from. Use GetDeviceID to get
such a device ID.
pathsToWatchRelativeToDevice:
An array of strings, each specifying a relative path to a directory on the device identified by the dev parameter. The paths should be relative to the root of the device. For example, if a volume ”MyData” is mounted
at ”/Volumes/MyData” and you want to watch ”/Volumes/MyData/Pictures/July”, specify a path string
of ”Pictures/July”. To watch the root of a volume pass a path of ”” (the empty string).
sinceWhen:
The service will supply events that have happened after the given event ID. To ask for events ”since now”
pass the constant kFSEventStreamEventIdSinceNow. Often, clients will supply the highest-numbered FSEventStreamEventId they have received in a callback, which they can obtain via the GetLatestEventId() accessor. Do not pass zero for sinceWhen, unless you want to receive events for every directory modified since
”the beginning of time” – an unlikely scenario.
latency:
The number of seconds the service should wait after hearing about an event from the kernel before passing
it along to the client via its event. Specifying a larger value may result in more effective temporal coalescing,
resulting in fewer callbacks.
flags:
Flags that modify the behavior of the stream being created.
On success the handle property is not 0.
See also:
• 12.1.4 Constructor(DeviceToWatch as Integer, path as string, sinceWhen as UInt64, latency as Double,
flags as Integer)
203
• 12.1.5 Constructor(DeviceToWatch as Integer, paths() as string, sinceWhen as UInt64, latency as
Double, flags as Integer)
205
• 12.1.6 Constructor(path as folderitem, sinceWhen as UInt64, latency as Double, flags as Integer) 205
• 12.1.7 Constructor(path as string, sinceWhen as UInt64, latency as Double, flags as Integer)
206
• 12.1.8 Constructor(paths() as folderitem, sinceWhen as UInt64, latency as Double, flags as Integer)
207
12.1. CLASS FSEVENTSMBS
12.1.10
209
Description as string
Plugin Version: 8.1, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: Returns a string
containing the description of the stream.
Notes: For debugging only.
12.1.11
DeviceBeingWatched as Integer
Plugin Version: 8.4, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: Fetches the dev t
supplied when the stream was created using a Device ID.
Notes: Returns 0 if there was an error.
12.1.12
ExclusionPaths as String()
Plugin Version: 16.0, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: Queries exclusion
paths.
12.1.13
FlushAsync as UInt64
Plugin Version: 8.1, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: Flushes all events.
Notes:
Asks the FS Events service to flush out any events that have occurred but have not yet been delivered, due to
the latency parameter that was supplied when the stream was created. This flushing occurs asynchronously
– do not expect the events to have already been delivered by the time this call returns. FlushAsync() can
only be called after the stream has been started, via Start().
Returns The largest event id of any event ever queued for this stream, otherwise zero if no events have been
queued for this stream.
12.1.14
FlushSync
Plugin Version: 8.1, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: Flushes all events.
Notes: Asks the FS Events service to flush out any events that have occurred but have not yet been delivered, due to the latency parameter that was supplied when the stream was created. This flushing occurs
synchronously – by the time this call returns, your callback will have been invoked for every event that had
already occurred at the time you made this call. FlushSync() can only be called after the stream has been
started, via Start().
210
12.1.15
CHAPTER 12. FOLDER CHANGE WATCHING
GetAbsoluteTime(theDate as date) as Double
Plugin Version: 8.4, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: Creates an absolute
time value based on the system time zone and the values in the date object.
Example:
dim d as new date
MsgBox str(FSEventsMBS.GetAbsoluteTime(d))
Notes: Returns 0 if the date parameter is nil or invalid.
12.1.16
GetCurrentEventId as UInt64
Plugin Version: 8.1, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: Fetches the most
recently generated event ID, system-wide (not just for one stream).
Notes: By thetime it is returned to your application even newer events may have already been generated.
12.1.17
GetDeviceID(volume as folderitem) as Integer
Plugin Version: 8.4, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: Returns the device
ID for the volume the folderitem points to.
Example:
dim v as FolderItem
v=volume(0)
MsgBox str(FSEventsMBS.GetDeviceID(v))
Notes: Returns 0 on any error.
12.1.18
GetLastEventIdForDeviceBeforeTime(DeviceID as Integer, theTime as
Double) as UInt64
Plugin Version: 8.4, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: Gets the last event
ID for the given device that was returned before the given time.
Example:
12.1. CLASS FSEVENTSMBS
211
dim d as new date
MsgBox str(FSEventsMBS.GetLastEventIdForDeviceBeforeTime(1,d.TotalSeconds))
Notes: This is conservative in the sense that if you then use the returned event ID as the sinceWhen parameter of the constructor that you will not miss any events that happened since that time. On the other
hand, you might receive some (harmless) extra events. Beware: there are things that can cause this to fail
to be accurate. For example, someone might change the system’s clock (either backwards or forwards). Or
an external drive might be used on different systems without perfectly synchronized clocks.
12.1.19
GetLatestEventId as UInt64
Plugin Version: 8.1, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: Fetches the sinceWhen property of the stream.
Notes: Upon receiving an event (and just before invoking the client’s callback) this attribute is updated to
the highest-numbered event ID mentioned in the event.
12.1.20
kFSEventStreamEventIdSinceNow as UInt64
Plugin Version: 16.0, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: A special value to
pass in if you mean the event ID for now.
Notes: Returns & hFFFFFFFFFFFFFFFF.
12.1.21
PathsBeingWatched as String()
Plugin Version: 8.4, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: Returns an array
with the paths being watched.
Notes: Works only on the RB Versions which support arry creation in plugins.
12.1.22
PurgeEventsForDeviceUpToEventId(DeviceID as Integer, EventID as
UInt64) as boolean
Plugin Version: 8.4, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: Purges old events
from the persistent per-volume database maintained by the service.
Notes: Can only be called by the root user.
212
12.1.23
CHAPTER 12. FOLDER CHANGE WATCHING
SetExclusionPaths(paths() as String) as boolean
Plugin Version: 16.0, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: Sets the exclusion
paths.
Notes:
Sets directories to be filtered from the EventStream.
A maximum of 8 directories maybe specified.
Requires OS X 10.9 or newer.
Returns true on success or false on failure.
12.1.24
Show
Plugin Version: 8.1, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: Prints a description
of the supplied stream to stderr.
Notes: For debugging only.
12.1.25
Start as boolean
Plugin Version: 8.1, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: Attempts to register
with the FS Events service to receive events per the parameters in the stream.
Notes:
Once started, the stream can be stopped via Stop().
Returns true if it succeeds, otherwise False if it fails. It ought to always succeed, but in the event it does
not then your code should fall back to performing recursive scans of the directories of interest as appropriate.
12.1.26
Stop
Plugin Version: 8.1, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: Unregisters with the
FS Events service.
Notes: The client callback will not be called for this stream while it is stopped. Stop() can only be called
if the stream has been started, via Start(). Once stopped, the stream can be restarted via Start(), at which
point it will resume receiving events from where it left off (”sinceWhen”).
12.1. CLASS FSEVENTSMBS
12.1.27
213
UUIDForDevice(DeviceID as Integer) as memoryblock
Plugin Version: 8.4, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: Gets the UUID
associated with a device, or nil if not possible (for example, on read-only device).
Notes: A (non-nil) UUID uniquely identifies a given stream of FSEvents. If this (non-nil) UUID is different than one that you stored from a previous run then the event stream is different (for example, because
FSEvents were purged, because the disk was erased, or because the event ID counter wrapped around back
to zero). A nil return value indicates that ”historical” events are not available, i.e., you should not supply a
”sinceWhen” value to the constructor other than kFSEventStreamEventIdSinceNow.
12.1.28
Properties
12.1.29
Handle as Integer
Plugin Version: 8.1, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: The internal stream
handle used.
Notes: (Read only property)
12.1.30
Running as Boolean
Plugin Version: 12.3, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: Whether this object
has been started.
Notes:
This is set to true when you call Start and set to false when you call Stop.
(Read only property)
12.1.31
Events
12.1.32
Callback(index as Integer, count as Integer, path as string, flags as
Integer, eventID as UInt64)
Plugin Version: 8.1, Console & Web: No, Mac: Yes, Win: No, Linux: No. Function: The callback received
when something changed.
Notes:
The plugin receives count events. This event is called count times with index going from 0 to count-1.
Path is the unix file path for the folder. A path might be ”/” if either of these flags is set for the event:
kFSEventStreamEventFlagUserDropped, kFSEventStreamEventFlagKernelDropped.
Flags: Flags to specify why the event was called. If no flags are set, then there was some change in the
directory at the specific path supplied in this event.
eventID: The event ID for this change. Each event ID comes from the most recent event being reported in the
214
CHAPTER 12. FOLDER CHANGE WATCHING
corresponding directory named in the path parameter. Event IDs all come from a single global source. They
are guaranteed to always be increasing, usually in leaps and bounds, even across system reboots and moving
drives from one machine to another. Just before invoking your callback your stream is updated so that calling
the accessor GetLatestEventId() will return the largest of the values passed in the eventIds parameter; if you
were to stop processing events from this stream after this callback and resume processing them later from
a newly-created FSEventStream, this is the value you would pass for the sinceWhen parameter to constructor.
12.1.33
Constants
12.1.34
kFSEventStreamCreateFlagFileEvents = 16
Plugin Version: 11.3. Function: One of the constants used to create a stream.
Notes:
Request file-level notifications. Your stream will receive events about individual files in the hierarchy you’re
watching instead of only receiving directory level notifications. Use this flag with care as it will generate
significantly more events than without it.
Available in Mac OS X 10.7 or newer.
12.1.35
kFSEventStreamCreateFlagIgnoreSelf = 8
Plugin Version: 11.3. Function: One of the constants used to create a stream.
Notes:
Don’t send events that were triggered by the current process. This is useful for reducing the volume of events
that are sent. It is only useful if your process might modify the file system hierarchy beneath the path(s)
being monitored. Note: this has no effect on historical events, i.e., those delivered before the HistoryDone
sentinel event.
Available in Mac OS X 10.7 or newer.
12.1.36
kFSEventStreamCreateFlagMarkSelf = 32
Plugin Version: 16.0. Function: One of the constants used to create a stream.
Notes: Tag events that were triggered by the current process with the ”OwnEvent” flag. This is only useful
if your process might modify the file system hierarchy beneath the path(s) being monitored and you wish to
know which events were triggered by your process. Note: this has no effect on historical events, i.e., those
delivered before the HistoryDone sentinel event.
12.1. CLASS FSEVENTSMBS
12.1.37
215
kFSEventStreamCreateFlagNoDefer = 2
Plugin Version: 8.1. Function: One of the constants used to create a stream.
Notes: Affects the meaning of the latency parameter. If you specify this flag and more than latency seconds have elapsed since the last event, your app will receive the event immediately. The delivery of the
event resets the latency timer and any further events will be delivered after latency seconds have elapsed.
This flag is useful for apps that are interactive and want to react immediately to changes but avoid getting
swamped by notifications when changes are occurringin rapid succession. If you do not specify this flag,
then when an event occurs after a period of no events, the latency timer is started. Any events that occur
during the next latency seconds will be delivered as one group (including that first event). The delivery
of the group of events resets the latency timer and any further events will be delivered after latency seconds. This is the default behavior and is more appropriate for background, daemon or batch processing apps.
12.1.38
kFSEventStreamCreateFlagNone = 0
Plugin Version: 8.1. Function: One of the constants used to create a stream.
12.1.39
kFSEventStreamCreateFlagUseCFTypes = 1
Plugin Version: 8.1. Function: One of the constants used to create a stream.
Notes: The plugin uses this one internally.
12.1.40
kFSEventStreamCreateFlagWatchRoot = 4
Plugin Version: 8.1. Function: One of the constants used to create a stream.
Notes: Request notifications of changes along the path to the path(s) you’re watching. For example, with
this flag, if you watch ”/foo/bar” and it is renamed to ”/foo/bar.old”, you would receive a RootChanged
event. The same is true if the directory ”/foo” were renamed. The event you receive is a special event:
the path for the event is the original path you specified, the flag kFSEventStreamEventFlagRootChanged
is set and event ID is zero. RootChanged events are useful to indicate that you should rescan a particular
hierarchy because it changed completely (as opposed to the things inside of it changing). If you want to
track the current location of a directory, it is best to open the directory before creating the stream so that
you have a file descriptor for it and can issue an F GETPATH fcntl() to find the current path.
12.1.41
kFSEventStreamEventFlagEventIdsWrapped = 8
Plugin Version: 8.1. Function: One of the flag values you can get on the callback event.
Notes: If kFSEventStreamEventFlagEventIdsWrapped is set, it means the 64-bit event ID counter wrapped
around. As a result, previously-issued event ID’s are no longer valid arguments for the sinceWhen parameter
216
CHAPTER 12. FOLDER CHANGE WATCHING
of the constructors.
12.1.42
kFSEventStreamEventFlagHistoryDone = 16
Plugin Version: 8.1. Function: One of the flag values you can get on the callback event.
Notes: Denotes a sentinel event sent to mark the end of the ”historical” events sent as a result of specifying a sinceWhen value in the constructor call that created this event stream. (It will not be sent if
kFSEventStreamEventIdSinceNow was passed for sinceWhen.) After invoking the client’s callback with all
the ”historical” events that occurred before now, the client’s callback will be invoked with an event where
the kFSEventStreamEventFlagHistoryDone flag is set. The client should ignore the path supplied in this
callback.
12.1.43
kFSEventStreamEventFlagItemChangeOwner = & h00004000
Plugin Version: 11.3. Function: One of the flags passed when you use FileEvents and a file changes.
Notes: File changed owner.
12.1.44
kFSEventStreamEventFlagItemCreated = & h00000100
Plugin Version: 11.3. Function: One of the flags passed when you use FileEvents and a file changes.
Notes: File created.
12.1.45
kFSEventStreamEventFlagItemFinderInfoMod = & h00002000
Plugin Version: 11.3. Function: One of the flags passed when you use FileEvents and a file changes.
Notes: File meta data in Finder info have changed.
12.1.46
kFSEventStreamEventFlagItemInodeMetaMod = & h00000400
Plugin Version: 11.3. Function: One of the flags passed when you use FileEvents and a file changes.
Notes: File meta data in inode have changed.
12.1.47
kFSEventStreamEventFlagItemIsDir = & h00020000
Plugin Version: 11.3. Function: One of the flags passed when you use FileEvents and a file changes.
Notes: File is a folder.
12.1. CLASS FSEVENTSMBS
12.1.48
kFSEventStreamEventFlagItemIsFile = & h00010000
Plugin Version: 11.3. Function: One of the flags passed when you use FileEvents and a file changes.
Notes: File is a regular file.
12.1.49
kFSEventStreamEventFlagItemIsHardlink = & h00100000
Plugin Version: 16.0. Function: One of the flags passed when you use FileEvents and a file changes.
Notes:
Indicates the object at the specified path supplied in this event is a hard link.
(This flag is only ever set if you specified the FileEvents flag when creating the stream.)
12.1.50
kFSEventStreamEventFlagItemIsLastHardlink = & h00200000
Plugin Version: 16.0. Function: One of the flags passed when you use FileEvents and a file changes.
Notes:
Indicates the object at the specific path supplied in this event was the last hard link.
(This flag is only ever set if you specified the FileEvents flag when creating the stream.)
12.1.51
kFSEventStreamEventFlagItemIsSymlink = & h00040000
Plugin Version: 11.3. Function: One of the flags passed when you use FileEvents and a file changes.
Notes: File is a symlink.
12.1.52
kFSEventStreamEventFlagItemModified = & h00001000
Plugin Version: 11.3. Function: One of the flags passed when you use FileEvents and a file changes.
Notes: File modified.
12.1.53
kFSEventStreamEventFlagItemRemoved = & h00000200
Plugin Version: 11.3. Function: One of the flags passed when you use FileEvents and a file changes.
Notes: File deleted.
217
218
12.1.54
CHAPTER 12. FOLDER CHANGE WATCHING
kFSEventStreamEventFlagItemRenamed = & h00000800
Plugin Version: 11.3. Function: One of the flags passed when you use FileEvents and a file changes.
Notes: File renamed.
12.1.55
kFSEventStreamEventFlagItemXattrMod = & h00008000
Plugin Version: 11.3. Function: One of the flags passed when you use FileEvents and a file changes.
Notes: Extended attributes changed.
12.1.56
kFSEventStreamEventFlagKernelDropped = 4
Plugin Version: 8.1. Function: One of the flag values you can get on the callback event.
Notes: The kFSEventStreamEventFlagUserDropped or kFSEventStreamEventFlagKernelDropped flags
may be set in addition to the kFSEventStreamEventFlagMustScanSubDirs flag to indicate that a problem occurred in buffering the events (the particular flag set indicates where the problem occurred) and that
the client must do a full scan of any directories (and their subdirectories, recursively) being monitored by
this stream. If you asked to monitor multiple paths with this stream then you will be notified about all of
them. Your code need only check for the kFSEventStreamEventFlagMustScanSubDirs flag; these flags (if
present) only provide information to help you diagnose the problem.
12.1.57
kFSEventStreamEventFlagMount = 64
Plugin Version: 8.1. Function: One of the flag values you can get on the callback event.
Notes: Denotes a special event sent when a volume is mounted. The path in the event is the path to the
newly-mounted volume. You will receive one of these notifications for every volume mount event inside the
kernel (independent of DiskArbitration). Beware that a newly-mounted volume could contain an arbitrarily
large directory hierarchy. Avoid pitfalls like triggering a recursive scan of a non-local filesystem, which you
can detect by checking for the absence of the MNT LOCAL flag in the f flags returned by statfs(). Also
be aware of the MNT DONTBROWSE flag that is set for volumes which should not be displayed by user
interface elements.
12.1.58
kFSEventStreamEventFlagMustScanSubDirs = 1
Plugin Version: 8.1. Function: One of the flag values you can get on the callback event.
Notes: Your application must rescan not just the directory given in the event, but all its children, recursively. This can happen if there was a problem whereby events were coalesced hierarchically. For example, an
event in /Users/jsmith/Music and an event in /Users/jsmith/Pictures might be coalesced into an event with
this flag set and path=/Users/jsmith. If this flag is set you may be able to get an idea of whether the bottleneck happened in the kernel (less likely) or in your client (more likely) by checking for the presence of the
12.1. CLASS FSEVENTSMBS
219
informational flags kFSEventStreamEventFlagUserDropped or kFSEventStreamEventFlagKernelDropped.
12.1.59
kFSEventStreamEventFlagNone = 0
Plugin Version: 8.1. Function: The constant to specify that no flags are used.
12.1.60
kFSEventStreamEventFlagOwnEvent = & h00080000
Plugin Version: 16.0. Function: One of the flags passed when you use FileEvents and a file changes.
Notes:
Indicates the event was triggered by the current process.
(This flag is only ever set if you specified the MarkSelf flag when creating the stream.)
12.1.61
kFSEventStreamEventFlagRootChanged = 32
Plugin Version: 8.1. Function: One of the flag values you can get on the callback event.
Notes: Denotes a special event sent when there is a change to one of the directories along the path to one
of the directories you asked to watch. When this flag is set, the event ID is zero and the path corresponds
to one of the paths you asked to watch (specifically, the one that changed). The path may no longer exist
because it or one of its parents was deleted or renamed. Events with this flag set will only be sent if you
passed the flag kFSEventStreamCreateFlagWatchRoot to the constructor when you created the stream.
12.1.62
kFSEventStreamEventFlagUnmount = 128
Plugin Version: 8.1. Function: One of the flag values you can get on the callback event.
Notes: Denotes a special event sent when a volume is unmounted. The path in the event is the path to the
directory from which the volume was unmounted. You will receive one of these notifications for every volume
unmount event inside the kernel. This is not a substitute for the notifications provided by the DiskArbitration framework; you only get notified after the unmount has occurred. Beware that unmounting a volume
could uncover an arbitrarily large directory hierarchy, although Mac OS X never does that.
12.1.63
kFSEventStreamEventFlagUserDropped = 2
Plugin Version: 8.1. Function: One of the flag values you can get on the callback event.
Notes: The kFSEventStreamEventFlagUserDropped or kFSEventStreamEventFlagKernelDropped flags
may be set in addition to the kFSEventStreamEventFlagMustScanSubDirs flag to indicate that a problem occurred in buffering the events (the particular flag set indicates where the problem occurred) and that
220
CHAPTER 12. FOLDER CHANGE WATCHING
the client must do a full scan of any directories (and their subdirectories, recursively) being monitored by
this stream. If you asked to monitor multiple paths with this stream then you will be notified about all of
them. Your code need only check for the kFSEventStreamEventFlagMustScanSubDirs flag; these flags (if
present) only provide information to help you diagnose the problem.
Chapter 13
Image Capture
13.1
class ICCameraDeviceMBS
13.1.1
class ICCameraDeviceMBS
Plugin Version: 14.3, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: ICCameraDeviceMBS is a concrete subclass of ICDeviceMBS class.
Notes:
ICDeviceBrowserMBS creates instances of this class.
Subclass of the ICDeviceMBS class.
This is an abstract class. You can’t create an instance, but you can get one from various plugin functions.
13.1.2
Methods
13.1.3
cancelDelete
Plugin Version: 14.3, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: Cancels the current
delete operation started by sending a requestDeleteFiles.
13.1.4
cancelDownload
Plugin Version: 14.3, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: Cancels the current
download operation.
221
222
13.1.5
CHAPTER 13. IMAGE CAPTURE
Constructor
Plugin Version: 14.3, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: The private constructor.
13.1.6
contents as ICCameraItemMBS()
Plugin Version: 14.3, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: Contents of the
camera.
Notes: The structure of the elements in this array will reflect the folder structure of the storage reported
by the camera. Each item in this array will correspond to a storage on the camera.
13.1.7
filesOfType(fileUTType as string) as ICCameraFileMBS()
Plugin Version: 14.3, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: This method returns
an array of files on the camera of type fileType.
Notes:
The fileType string is one of the following Uniform Type Identifier strings: kUTTypeImage, kUTTypeMovie,
kUTTypeAudio, or kUTTypeData.
See UTTypeMBS module.
13.1.8
ICCameraDeviceCanAcceptPTPCommands as string
Plugin Version: 14.3, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: One of the constants
used to describe capabilities of a camera.
Notes: Indicates that the camera can accept PTP commands.
13.1.9
ICCameraDeviceCanDeleteAllFiles as string
Plugin Version: 14.3, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: One of the constants
used to describe capabilities of a camera.
Notes: Indicates that the camera can delete all files in a single operation while it is connected.
13.1.10
ICCameraDeviceCanDeleteOneFile as string
Plugin Version: 14.3, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: One of the constants
used to describe capabilities of a camera.
13.1. CLASS ICCAMERADEVICEMBS
223
Notes: Indicates that the camera can delete a file at a time while it is connected.
13.1.11
ICCameraDeviceCanReceiveFile as string
Plugin Version: 14.3, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: One of the constants
used to describe capabilities of a camera.
Notes: Indicates that the host can upload files to the camera.
13.1.12
ICCameraDeviceCanSyncClock as string
Plugin Version: 14.3, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: One of the constants
used to describe capabilities of a camera.
Notes: Indicates that the camera can synchronize its date and time with that of the host computer.
13.1.13
ICCameraDeviceCanTakePicture as string
Plugin Version: 14.3, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: One of the constants
used to describe capabilities of a camera.
Notes: Indicates that the camera can capture a picture while it is connected, if the client sends a requestTakePicture message to it.
13.1.14
ICCameraDeviceCanTakePictureUsingShutterReleaseOnCamera as string
Plugin Version: 14.3, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: One of the constants
used to describe capabilities of a camera.
Notes: Indicates that the camera can capture a picture while it is connected, if the user presses the shutter
release on the camera.
13.1.15
ICDeleteAfterSuccessfulDownload as string
Plugin Version: 14.3, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: One of the keys for
options dictionary.
Notes: The value for this key should be a boolean value. If this value is true, the file will be deleted from
the device after it is succcessfully downloaded.
224
13.1.16
CHAPTER 13. IMAGE CAPTURE
ICDownloadsDirectoryURL as string
Plugin Version: 14.3, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: One of the keys for
options dictionary.
Notes:
The value for this key should be an CFURLMBS referencing a writable directory.
The downloaded files will be saved in that directory.
13.1.17
ICDownloadSidecarFiles as string
Plugin Version: 14.3, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: One of the keys for
options dictionary.
Notes: The value for this key should be a boolean value. If this value is true, all sidecar files will be
downloaded along with the media file.
13.1.18
ICOverwrite as string
Plugin Version: 14.3, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: One of the keys for
options dictionary.
Notes: The value for this key should be a boolean value. If this value is true, the downloaded file will
overwrite an existing file with the same name and extension.
13.1.19
ICSaveAsFilename as string
Plugin Version: 14.3, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: One of the keys for
options dictionary.
Notes: The value for this key should be a string containing the name to be used for the downloaded file.
13.1.20
ICSavedAncillaryFiles as string
Plugin Version: 14.3, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: One of the keys for
options dictionary.
Notes: The value for this key will be an array containing names of files associated with the primary file
that is downloaded. The options dictionary returned in didDownloadFile may have this key.
13.1. CLASS ICCAMERADEVICEMBS
13.1.21
225
ICSavedFilename as string
Plugin Version: 14.3, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: One of the keys for
options dictionary.
Notes: The value for this key will be a string containing the actual name of the saved file. The options
dictionary returned in didDownloadFile will have this key.
13.1.22
mediaFiles as ICCameraFileMBS()
Plugin Version: 14.3, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: The property
mediaFiles represents all image, movie and audio files on the camera.
Notes: These files are returned as a single array without regard to the folder hierarchy used to store these
files on the camera.
13.1.23
requestDeleteFiles(files() as ICCameraFileMBS)
Plugin Version: 14.3, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: Deletes files.
13.1.24
requestDisableTethering
Plugin Version: 14.3, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: Send this message
to disable tethered capture on the camera device if the camera has the ’ICCameraDeviceCanTakePicture’
capability and if your process has already sent a ’requestEnableTethering’ to it.
13.1.25
requestDownloadFile(file as ICCameraFileMBS, options as dictionary
= nil)
Plugin Version: 14.3, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: Download a file
from the camera. Please refer to the top of this header for information about the options.
Notes:
Calls cameraDeviceDidDownloadFile event later.
The content of error returned should be examined to determine if the request completed successfully.
13.1.26
requestEnableTethering
Plugin Version: 14.3, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: Send this message
to enable tethered capture on the camera device if the camera has the ’ICCameraDeviceCanTakePicture’
226
CHAPTER 13. IMAGE CAPTURE
capability.
13.1.27
requestReadDataFromFile(file as ICCameraFileMBS, offset as UInt64,
Length as UInt64)
Plugin Version: 14.3, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: This method
asynchronously reads data of a specified length from a specified offset.
Notes:
Calls later ImageCaptureEventsMBS.cameraDeviceDidReadData event.
The content of error returned should be examined to determine if the request completed successfully.
13.1.28
requestSendPTPCommand(command as MemoryBlock, dataOut as MemoryBlock)
Plugin Version: 14.3, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: This method
asynchronously sends a PTP command to a camera.
Notes: The content of error returned should be examined to determine if the request completed successfully.
13.1.29
requestSyncClock
Plugin Version: 14.3, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: Synchronize camera’s clock with the computer’s clock.
Notes: You should send this request only if the camera has the ’ICCameraDeviceCanSyncClock’ capability.
13.1.30
requestTakePicture
Plugin Version: 14.3, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: Capture a new
image using the camera, the camera capabilities include ’ICCameraDeviceCanTakePicture’.
Notes: You MUST send ’requestEnableTethering’ message to the camera before sending ’requestTakePicture’ message.
13.1.31
requestUploadFile(file as folderitem, options as dictionary = nil)
Plugin Version: 14.3, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: Upload a file at
fileURL to the camera.
Notes:
13.1. CLASS ICCAMERADEVICEMBS
227
The options dictionary is not used in this version.
Calls later ImageCaptureEventsMBS.cameraDeviceDidUploadFile event.
The content of error returned should be examined to determine if the request completed successfully.
13.1.32
Properties
13.1.33
batteryLevel as Integer
Plugin Version: 14.3, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: Indicates the battery
charge level.
Notes:
Its value ranges from 0 to 100.
(Read only property)
13.1.34
batteryLevelAvailable as Boolean
Plugin Version: 14.3, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: Indicates if the
device has reported battery charge level.
Notes: (Read only property)
13.1.35
contentCatalogPercentCompleted as Integer
Plugin Version: 14.3, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: Indicates the
percentage of content cataloging completed on the device.
Notes:
Its value ranges from 0 to 100.
(Read only property)
13.1.36
isAccessRestrictedAppleDevice as Boolean
Plugin Version: 14.3, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: Set to true if the
device is made by Apple and is pass-coded locked and connected to an untrusted host.
Notes: (Read only property)
228
13.1.37
CHAPTER 13. IMAGE CAPTURE
mountPoint as String
Plugin Version: 14.3, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: Filesystem mount
point for a device with transportType of ICTransportTypeMassStorage.
Notes:
This will be ”” for all other devices.
(Read only property)
13.1.38
tetheredCaptureEnabled as Boolean
Plugin Version: 14.3, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: This property is set
to YES when tethered capture is enabled on the device.
Notes:
Use ’requestEnableTethering’ and ’requestDisableTethering’ to enable or disable tethered capture on the
device.
(Read only property)
13.1.39
timeOffset as Double
Plugin Version: 14.3, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: Indicates the time
offset, in seconds, between the camera’s clock and the computer’s clock.
Notes:
This value is positive if the camera’s clock is ahead of the computer’s clock. This property should be ignored
if the camera’s capabilities property does not contain ICCameraDeviceCanSyncClock.
(Read only property)
13.2. CLASS ICCAMERAFILEMBS
13.2
class ICCameraFileMBS
13.2.1
class ICCameraFileMBS
229
Plugin Version: 14.3, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: This class represents
a file on an ICCameraDevice object.
Notes:
Subclass of the ICCameraItemMBS class.
This is an abstract class. You can’t create an instance, but you can get one from various plugin functions.
13.2.2
Methods
13.2.3
Constructor
Plugin Version: 14.3, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: The private constructor.
13.2.4
sidecarFiles as ICCameraFileMBS()
Plugin Version: 14.3, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: Returns array of
sidecar files.
Notes: This property is an empty array if there are no sidecar files associated with this file. Otherwise it is
an array of ICCameraFile instances of sidecar files associated with this file. An example of a sidecar file is
a file with the same base name as this file and having an extension XMP.
13.2.5
Properties
13.2.6
Duration as Double
Plugin Version: 14.3, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: Duration of audio/video file in seconds.
Notes: (Read only property)
13.2.7
FileSize as UInt64
Plugin Version: 14.3, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: Size of file in bytes.
Notes: (Read only property)
230
13.2.8
CHAPTER 13. IMAGE CAPTURE
Orientation as Integer
Plugin Version: 14.3, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: Desired orientation
of image to use when it is downloaded.
Notes:
This property is set to ICEXIFOrientation1 initially. If the format of this file supports EXIF orientation
tag, then this property will be updated to match the value of that tag, when the thumbnail or metadata for
this file is received.
Possible values:
ICEXIFOrientation1
ICEXIFOrientation2
ICEXIFOrientation3
ICEXIFOrientation4
ICEXIFOrientation5
ICEXIFOrientation6
ICEXIFOrientation7
ICEXIFOrientation8
1
2
3
4
5
6
7
8
(Read and Write property)
Normal
Flipped horizontally
Rotated 180
Flipped vertically
Rotated 90 CCW and flipped vertically
Rotated 90 CCW
Rotated 90 CW and flipped vertically
Rotated 90 CW
13.3. CLASS ICCAMERAFOLDERMBS
13.3
class ICCameraFolderMBS
13.3.1
class ICCameraFolderMBS
231
Plugin Version: 14.3, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: This class represents
a folder on an ICCameraDevice object.
Notes:
Subclass of the ICCameraItemMBS class.
This is an abstract class. You can’t create an instance, but you can get one from various plugin functions.
13.3.2
Methods
13.3.3
Constructor
Plugin Version: 14.3, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: The private constructor.
13.3.4
contents as ICCameraItemMBS()
Plugin Version: 14.3, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: A list of items
contained by this folder.
232
CHAPTER 13. IMAGE CAPTURE
13.4
class ICCameraItemMBS
13.4.1
class ICCameraItemMBS
Plugin Version: 14.3, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: ICCameraItem is
an abstract class that represents an item in an ICCameraDevice object.
Notes:
ICCameraDevice object creates instances of two concrete subclasses of ICCameraItem: ICCameraFolder and
ICCameraFile.
This is an abstract class. You can’t create an instance, but you can get one from various plugin functions.
13.4.2
Methods
13.4.3
Constructor
Plugin Version: 14.3, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: The private constructor.
13.4.4
Properties
13.4.5
addedAfterContentCatalogCompleted as Boolean
Plugin Version: 14.3, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: This property is set
if the file is captured on the device after the device’s content is fully enumerated.
Notes:
This does not apply to files added as a result of adding a new store to the device.
(Read only property)
13.4.6
CreationDate as Date
Plugin Version: 14.3, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: Creation date of
this file.
Notes:
This information is usually the same as the EXIF creation date.
(Read only property)
13.4. CLASS ICCAMERAITEMMBS
13.4.7
233
Device as ICCameraDeviceMBS
Plugin Version: 14.3, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: Parent device of
this folder.
Notes: (Read only property)
13.4.8
FileSystemPath as String
Plugin Version: 14.3, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: The file system
path of the item for items on a device with transportType of ICTransportTypeMassStorage.
Notes: (Read only property)
13.4.9
Handle as Integer
Plugin Version: 14.3, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: The internal object
reference.
Notes: (Read and Write property)
13.4.10
InTemporaryStore as Boolean
Plugin Version: 14.3, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: Indicates if this
folder is in a temporary store.
Notes:
A temporary store may be used by the device when images are captures on the device when it is tethered
to the computer.
(Read only property)
13.4.11
largeThumbnailIfAvailable as Variant
Plugin Version: 14.3, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: Large thumbnail
for the item if one is readily available.
Notes:
Value is a CGImageMBS.
If one is not readily available, accessing this property will send a message to the device requesting a
thumbnail for the file. The ImageCaptureEventsMBS subclass will be notified via event cameraDeviceDidReceiveThumbnailForItem.
(Read only property)
234
13.4.12
CHAPTER 13. IMAGE CAPTURE
Locked as Boolean
Plugin Version: 14.3, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: Indicates the
protection state of this item.
Notes:
It is locked if the storage card in the camera is locked.
(Read only property)
13.4.13
MetadataIfAvailable as Dictionary
Plugin Version: 14.3, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: Metadata for the
file if one is readily available.
Notes:
If one is not readily available, accessing this property will send a message to the device requesting a thumbnail
for the file. The ImageCaptureEventsMBS subclass will be notified via event cameraDeviceDidReceiveMetadataForItem.
(Read only property)
13.4.14
ModificationDate as Date
Plugin Version: 14.3, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: Modification date
of this file.
Notes:
This information is usually the same as the EXIF modification date.
(Read only property)
13.4.15
Name as String
Plugin Version: 14.3, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: Name of this file or
folder.
Notes: (Read only property)
13.4.16
ParentFolder as ICCameraFolderMBS
Plugin Version: 14.3, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: Parent folder of this
folder. The root folder’s parentFolder is nil.
Notes: (Read only property)
13.4. CLASS ICCAMERAITEMMBS
13.4.17
235
ptpObjectHandle as Integer
Plugin Version: 14.3, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: PTP object handle
value if the item is on a camera that uses PTP protocol.
Notes:
The value of this property is set to 0 if the camera does not use PTP protocol.
(Read only property)
13.4.18
Raw as Boolean
Plugin Version: 14.3, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: Indicates if the file
is a raw image file.
Notes: (Read only property)
13.4.19
thumbnailIfAvailable as Variant
Plugin Version: 14.3, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: Thumbnail for the
item if one is readily available.
Notes:
Value is a CGImageMBS.
If one is not readily available, accessing this property will send a message to the device requesting a
thumbnail for the file. The ImageCaptureEventsMBS subclass will be notified via event cameraDeviceDidReceiveThumbnailForItem.
(Read only property)
13.4.20
UserData as Dictionary
Plugin Version: 14.3, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: A mutable dictionary
to store arbitrary key-value pairs associated with a camera item object.
Notes:
This can be used by view objects that bind to this object to store ”house-keeping” information.
In Xojo, please query dictionary, modify it and assign back to this property.
(Read and Write property)
13.4.21
UTI as String
Plugin Version: 14.3, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: Item UTI.
Notes:
236
CHAPTER 13. IMAGE CAPTURE
This is an Uniform Type Identifier string. It is one of: kUTTypeFolder, kUTTypeImage, kUTTypeMovie,
kUTTypeAudio, or kUTTypeData.
See UTTypeMBS module.
(Read only property)
13.5. CLASS ICDEVICEBROWSERMBS
13.5
class ICDeviceBrowserMBS
13.5.1
class ICDeviceBrowserMBS
237
Plugin Version: 14.3, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: The ICDeviceBrowser object is used to find devices such as digital cameras and scanners that are supported by Image
Capture.
Notes: These device may be directly attached to the USB or FireWire bus on the host computer, shared by
other computers, or available over a TCP/IP network. This object communicates with an Image Capture
agent process asynchronously to accomplish this.
13.5.2
Methods
13.5.3
Constructor
Plugin Version: 14.3, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: The constructor.
13.5.4
Destructor
Plugin Version: 16.4, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: The destructor.
13.5.5
devices as ICDeviceMBS()
Plugin Version: 14.3, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: All devices found
by the browser.
Notes: This property will change as devices appear and disappear. This array is empty before the first
invocation of the deviceBrowserDidAddDevice event.
13.5.6
Start
Plugin Version: 14.3, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: This message tells
the receiver to start looking for devices.
Notes: Please use ImageCaptureEventsMBS class to receive events.
238
13.5.7
CHAPTER 13. IMAGE CAPTURE
Stop
Plugin Version: 14.3, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: This method tells
the receiver to stop looking for devices.
Notes: This will free all device instances that are not in use.
13.5.8
Properties
13.5.9
browsedDeviceTypeMask as Integer
Plugin Version: 14.3, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: The device type
mask.
Notes:
A mask whose set bits indicate the type of device(s) being browsed after the receiver receives the start
message. This property can be changed while the browser is browsing for devices. This property can be
constructed by OR’d values of ICDeviceTypeMask with values of ICDeviceLocationTypeMask.
(Read and Write property)
13.5.10
Browsing as Boolean
Plugin Version: 14.3, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: Indicates whether
the device browser is browsing for devices.
Notes: (Read only property)
13.5.11
Handle as Integer
Plugin Version: 14.3, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: The internal object
reference.
Notes: (Read and Write property)
13.5.12
preferredDevice as ICDeviceMBS
Plugin Version: 14.3, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: This method returns
a device object that should be selected by the client application when it is launched.
Notes:
If the client application that calls this method is the auto-launch application associated with a device and
that device is the last device attached (through USB, FireWire or network), then that device will be the
preferred device. The best place to call this method is in the event deviceBrowserDidAddDevice, if the
13.5. CLASS ICDEVICEBROWSERMBS
239
”moreComing” parameter passed to the delegate is false; or in the event deviceBrowserDidEnumerateLocalDevices.
(Read only property)
13.5.13
Events
13.5.14
DeviceDidChangeName(device as ICDeviceMBS)
Plugin Version: 14.3, Console & Web: No, Mac: Yes, Win: No, Linux: No. Function: This event is sent if
the name of a device changes.
Notes: This happens if the device module overrides the default name of the device reported by the device’s
transport layer, or if the name of the filesystem volume mounted by the device is changed by the user.
13.5.15
DeviceDidChangeSharingState(device as ICDeviceMBS)
Plugin Version: 14.3, Console & Web: No, Mac: Yes, Win: No, Linux: No. Function: This event is sent
when the sharing state of a device has changes.
Notes: Any Image Capture client application can choose to share the device over the network using the
sharing or webSharing facility in Image Capture.
13.5.16
DidAddDevice(device as ICDeviceMBS, moreComing as boolean)
Plugin Version: 14.3, Console & Web: No, Mac: Yes, Win: No, Linux: No. Function: This event is sent to
inform that a device has been added.
Notes: If several devices are found during the initial search, then this event is sent once for each device
with the value of ’moreComing’ set to true in each event except the last one.
13.5.17
DidEnumerateLocalDevices
Plugin Version: 14.3, Console & Web: No, Mac: Yes, Win: No, Linux: No. Function: This event is sent
after the device browser completes sending deviceBrowser:didAddDevice event for all local devices.
Notes: Detecting locally connected devices (USB and FireWire devices) is faster than detecting devices
connected using a network protocol. An Image Capture client application may use this event to update its
user interface to let the user know that it has completed looking for locally connected devices and then start
looking for network devices.
240
13.5.18
CHAPTER 13. IMAGE CAPTURE
DidRemoveDevice(device as ICDeviceMBS, moreGoing as boolean)
Plugin Version: 14.3, Console & Web: No, Mac: Yes, Win: No, Linux: No. Function: This event is sent to
the delegate to inform that a device has been removed.
Notes: If several devices are removed at the same time, then this event is sent once for each device with
the value of ’moreGoing’ set to true in each event except the last one.
13.5.19
RequestsSelectDevice(device as ICDeviceMBS)
Plugin Version: 14.3, Console & Web: No, Mac: Yes, Win: No, Linux: No. Function: This event is sent
when an event that occurred on the device may be of interest to the client application.
Notes: In Mac OS X 10.6, this event is sent when a button is pressed on a device and the current application
is the target for that button press. In the case of the button-press event, if a session is open on the device,
this event will not be sent, instead the deviceDidReceiveButtonPress event is sent.
13.6. CLASS ICDEVICEMBS
13.6
class ICDeviceMBS
13.6.1
class ICDeviceMBS
241
Plugin Version: 14.3, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: ICDevice is an
abstract class that represents a device supported by Image Capture.
Notes:
ImageCaptureCore defines two concrete subclasses of ICDeviceMBS, ICCameraDeviceMBS and ICScannerDeviceMBS. ICDeviceBrowserMBS creates instances of these two subclasses to represent cameras and
scanners it finds.
This is an abstract class. You can’t create an instance, but you can get one from various plugin functions.
13.6.2
Methods
13.6.3
capabilities as Variant()
Plugin Version: 14.3, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: The capabilities of
the device as reported by the device module.
13.6.4
Constructor
Plugin Version: 14.3, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: The private constructor.
13.6.5
ICButtonTypeCopy as string
Plugin Version: 14.3, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: One of the constants
used to identify button-press on a device.
Notes: Indicates that the ”Copy” button on the device was pressed.
13.6.6
ICButtonTypeMail as string
Plugin Version: 14.3, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: One of the constants
used to identify button-press on a device.
Notes: Indicates that the ”Mail” button on the device was pressed.
242
13.6.7
CHAPTER 13. IMAGE CAPTURE
ICButtonTypePrint as string
Plugin Version: 14.3, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: One of the constants
used to identify button-press on a device.
Notes: Indicates that the ”Print” button on the device was pressed.
13.6.8
ICButtonTypeScan as string
Plugin Version: 14.3, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: One of the constants
used to identify button-press on a device.
Notes: Indicates that the ”Scan” button on the device was pressed.
13.6.9
ICButtonTypeTransfer as string
Plugin Version: 14.3, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: One of the constants
used to identify button-press on a device.
Notes: Indicates that the ”Transfer” button on the device was pressed.
13.6.10
ICButtonTypeWeb as string
Plugin Version: 14.3, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: One of the constants
used to identify button-press on a device.
Notes: Indicates that the ”Web” button on the device was pressed.
13.6.11
ICDeviceCanEjectOrDisconnect as string
Plugin Version: 14.3, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: One of the constants
used to describe capabilities of a device.
Notes: Indicates either the device is mounted as a mass-storage volume and can be ejected or the it is a
remote device with an active connection that can be disconnected.
13.6.12
ICDeviceLocationDescriptionBluetooth as string
Plugin Version: 14.3, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: This description is
returned for locationDescription property of a device connected via Bluetooth.
13.6. CLASS ICDEVICEMBS
13.6.13
243
ICDeviceLocationDescriptionFireWire as string
Plugin Version: 14.3, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: This description is
returned for locationDescription property of a device connected to a FireWire port.
13.6.14
ICDeviceLocationDescriptionMassStorage as string
Plugin Version: 14.3, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: This description is
returned for locationDescription property of a device that is mounted as a mass-storage volume.
13.6.15
ICDeviceLocationDescriptionUSB as string
Plugin Version: 14.3, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: This description is
returned for locationDescription property of a device connected to a USB port.
13.6.16
ICLocalizedStatusNotificationKey as string
Plugin Version: 14.3, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: One of the constants
used for device status notifications.
Notes: Key for a localized notification string.
13.6.17
ICStatusCodeKey as string
Plugin Version: 14.3, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: One of the constants
used for device status notifications.
Notes: One of values defined in ICReturnCode.
13.6.18
ICStatusNotificationKey as string
Plugin Version: 14.3, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: One of the constants
used for device status notifications.
Notes: Key for a non-localized notification string.
244
13.6.19
CHAPTER 13. IMAGE CAPTURE
ICTransportTypeBluetooth as string
Plugin Version: 14.3, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: Indicates that the
device uses Bluetooth transport.
13.6.20
ICTransportTypeFireWire as string
Plugin Version: 14.3, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: Indicates that the
device uses FireWire transport.
13.6.21
ICTransportTypeMassStorage as string
Plugin Version: 14.3, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: Indicates that the
device use mounts as a mass-storage volume.
13.6.22
ICTransportTypeTCPIP as string
Plugin Version: 14.3, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: Indicates that the
device uses TCP/IP transport.
Notes: These devices are discovered using Bonjour.
13.6.23
ICTransportTypeUSB as string
Plugin Version: 14.3, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: Indicates that the
device uses USB transport.
13.6.24
requestCloseSession
Plugin Version: 14.3, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: This message
requests to close a previously opened session on this device.
Notes: This request is completed when the ImageCaptureEventsMBS subclass receives a deviceDidCloseSessionWithError event.
13.6. CLASS ICDEVICEMBS
13.6.25
245
requestEjectOrDisconnect
Plugin Version: 14.3, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: Eject the media if
permitted by the device, or disconnect from a remote device.
13.6.26
requestOpenSession
Plugin Version: 14.3, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: This message
requests to open a session on the device.
Notes:
A client MUST open a session on a device in order to use the device.
This request is completed when the ImageCaptureEventsMBS subclass receives a deviceDidOpenSessionWithError event. No more events will be sent to the delegate if this request fails.
13.6.27
requestSendMessage(messageCode as UInt32, data as MemoryBlock,
maxReturnedDataSize as UInt64)
Plugin Version: 14.3, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: This method
asynchronously sends an arbitrary message with optional data to a device.
Notes:
This method allows developers to send a private message from a client application to a device module. This
method is the functional equivalent of calling ICAObjectSendMessage() found in ImageCapture.framework,
which has been deprecated in Mac OS X 10.6. The response to this command will be delivered using deviceDidSendMessage event.
The content of error returned should be examined to determine if the request completed successfully.
NOTE: This method SHOULD NOT BE USED to send PTP pass-through commands to a PTP camera.
Please refer to requestSendPTPCommand defined in ICCameraDeviceMBS for sending PTP pass-through
commands.
13.6.28
requestYield
Plugin Version: 14.3, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: This message
requests the device module in control of this device to yield control.
Notes: This message should be used only if the client is planning on communiting with the device directly.
The device module may not yield control of the device if it has an open session.
246
CHAPTER 13. IMAGE CAPTURE
13.6.29
Properties
13.6.30
AutolaunchApplicationPath as String
Plugin Version: 14.3, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: Filesystem path of
an application that is to be automatically launched when this device is added.
Notes: (Read and Write property)
13.6.31
BonjourServiceType as String
Plugin Version: 17.0, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: Service type if
device was found via Bonjour..
Notes: (Read only property)
13.6.32
BskonjourServiceName as String
Plugin Version: 17.0, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: Service name if
device was found via Bonjour..
Notes: (Read only property)
13.6.33
ButtonPressed as String
Plugin Version: 14.3, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: A string object with
one of the ICButtonType* values defined above.
Notes: (Read only property)
13.6.34
canDeleteAllFiles as Boolean
Plugin Version: 14.3, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: If all files can be
deleted.
Notes: (Read only property)
13.6.35
canDeleteOneFile as Boolean
Plugin Version: 14.3, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: Whether a file can
be deleted.
13.6. CLASS ICDEVICEMBS
247
Notes: (Read only property)
13.6.36
canEject as Boolean
Plugin Version: 14.3, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: Whether this device
can be ejected.
Notes: (Read only property)
13.6.37
canReceiveFile as Boolean
Plugin Version: 14.3, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: Whether this device
can receive a file.
Notes: (Read only property)
13.6.38
canSyncClock as Boolean
Plugin Version: 14.3, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: Whether this device
can sync clock.
Notes: (Read only property)
13.6.39
canTakePicture as Boolean
Plugin Version: 14.3, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: Whether this device
can take pictures.
Notes: (Read only property)
13.6.40
fwGUID as Int64
Plugin Version: 14.3, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: The FireWire GUID
of a FireWire device in the IOKit registry.
Notes:
This will be 0 for non-FireWire devices.
(Read only property)
248
13.6.41
CHAPTER 13. IMAGE CAPTURE
Handle as Integer
Plugin Version: 14.3, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: The internal object
reference.
Notes: (Read and Write property)
13.6.42
HasConfigurableWiFiInterface as Boolean
Plugin Version: 14.3, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: Indicates whether
the device can be configured for use on a WiFi network.
Notes: (Read only property)
13.6.43
HasOpenSession as Boolean
Plugin Version: 14.3, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: Indicates whether
the device has an open session.
Notes: (Read only property)
13.6.44
Icon as Variant
Plugin Version: 14.3, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: Icon image for the
device.
Notes:
Value is a CGImageMBS.
(Read only property)
13.6.45
IconPath as String
Plugin Version: 17.0, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: Path to icon file.
Notes: (Read only property)
13.6.46
IPAddress as String
Plugin Version: 17.0, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: IP Address.
Notes: (Read only property)
13.6. CLASS ICDEVICEMBS
13.6.47
249
IsRemote as Boolean
Plugin Version: 14.3, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: Indicates whether
the device is a remote device published by Image Capture device sharing facility.
Notes: (Read only property)
13.6.48
IsShared as Boolean
Plugin Version: 14.3, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: Indicates whether
the device is shared using the Image Capture device sharing facility.
Notes:
This value will change when sharing of this device is enabled or disabled.
(Read only property)
13.6.49
LocationDescription as String
Plugin Version: 14.3, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: A non-localized
location description string for the device.
Notes:
The value returned in one of the location description strings defined above, or location obtained from the
Bonjour TXT record of a network device.
(Read only property)
13.6.50
ModuleExecutableArchitecture as Integer
Plugin Version: 14.3, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: Executable
Architecture of the device module in control of this device.
Notes:
Possible values:
I386
PPC
X86 64
PPC64
&
&
&
&
h00000007
h00000012
h01000007
h01000012
(Read only property)
250
13.6.51
CHAPTER 13. IMAGE CAPTURE
ModulePath as String
Plugin Version: 14.3, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: Filesystem path of
the device module that is associated with this device.
Notes:
Camera-specific capabilities are defined in ICCameraDeviceMBS class and scanner-specific capabilities are
defined in ICScannerDeviceMBS class.
(Read only property)
13.6.52
ModuleVersion as String
Plugin Version: 14.3, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: The bundle version
of the device module associated with this device.
Notes:
This may change if an existing device module associated with this device is updated or a new device module
for this device is installed.
(Read only property)
13.6.53
Name as String
Plugin Version: 14.3, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: Name of the device
as reported by the device module or by the device transport when a device module is not in control of this
device.
Notes:
This name may change if the device module overrides the default name of the device reported by the device’s
transport, or if the name of the filesystem volume mounted by the device is changed by the user.
(Read only property)
13.6.54
PersistentIDString as String
Plugin Version: 14.3, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: A string representation of the persistent ID of the device.
Notes: (Read only property)
13.6.55
ProductKind as String
Plugin Version: 17.0, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: Product kind.
Notes: (Read only property)
13.6. CLASS ICDEVICEMBS
13.6.56
251
SerialNumberString as String
Plugin Version: 14.3, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: The serial number
of the device.
Notes:
This will be ”” if the device does not provide a serial number.
(Read only property)
13.6.57
TransportType as String
Plugin Version: 14.3, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: The transport type
used by the device.
Notes:
The possible values are: ICTransportTypeUSB, ICTransportTypeFireWire, ICTransportTypeBluetooth, ICTransportTypeTCPIP, or ICTransportTypeMassStorage.
(Read only property)
13.6.58
type as Integer
Plugin Version: 14.3, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: The type of the
device as defined by ICDeviceType OR’d with its ICDeviceLocationType.
Notes:
The type of this device can be obtained by AND’ing the value retuned by this property with an appropriate
ICDeviceTypeMask. The location type of this device can be obtained by AND’ing the value retuned by this
property with an appropriate ICDeviceLocationTypeMask.
(Read only property)
13.6.59
usbLocationID as Integer
Plugin Version: 14.3, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: The USB location
ID of a USB device in the IOKit registry.
Notes:
This will be 0 for non-USB devices.
(Read only property)
252
13.6.60
CHAPTER 13. IMAGE CAPTURE
usbProductID as Integer
Plugin Version: 14.3, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: The USB product
ID of a USB device in the IOKit registry.
Notes:
This will be 0 for non-USB devices.
(Read only property)
13.6.61
usbVendorID as Integer
Plugin Version: 14.3, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: The USB vendor
ID of a USB device in the IOKit registry.
Notes:
This will be 0 for non-USB devices.
(Read only property)
13.6.62
UserData as Dictionary
Plugin Version: 14.3, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: A mutable dictionary
to store arbitrary key-value pairs associated with a device object.
Notes:
This can be used by view objects that bind to this object to store ”house-keeping” information.
In Xojo, please query dictionary, modify it and assign back to this property.
(Read and Write property)
13.6.63
UUIDString as String
Plugin Version: 14.3, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: A string representation of the Universally Unique ID of the device.
Notes: (Read only property)
13.6.64
Constants
13.6.65
ICDeviceLocationTypeBluetooth = & h00000800
Plugin Version: 14.3. Function: One of the device types.
Notes: Device found as a paired Bluetooth device.
13.6. CLASS ICDEVICEMBS
13.6.66
ICDeviceLocationTypeBonjour = & h00000400
Plugin Version: 14.3. Function: One of the device types.
Notes: Device found over the network by searching for Bonjour services supported by Image Capture.
13.6.67
ICDeviceLocationTypeLocal = & h00000100
Plugin Version: 14.3. Function: One of the device types.
Notes: Device found directly attached to the Macintosh via its USB or FireWire port.
13.6.68
ICDeviceLocationTypeMaskBluetooth = & h00000800
Plugin Version: 14.3. Function: One of the Image Capture Device Location Type Masks.
Notes: Mask to detect paired Bluetooth device.
13.6.69
ICDeviceLocationTypeMaskBonjour = & h00000400
Plugin Version: 14.3. Function: One of the Image Capture Device Location Type Masks.
Notes: Mask to detect a network device that publishes a Bonjour service.
13.6.70
ICDeviceLocationTypeMaskLocal = & h00000100
Plugin Version: 14.3. Function: One of the Image Capture Device Location Type Masks.
Notes: Mask to detect a local (e.g., USB or FireWire) device.
13.6.71
ICDeviceLocationTypeMaskRemote = & h0000FE00
Plugin Version: 14.3. Function: One of the Image Capture Device Location Type Masks.
Notes: Mask to detect a remote (shared, Bonjour, Bluetooth) device.
13.6.72
ICDeviceLocationTypeMaskShared = & h00000200
Plugin Version: 14.3. Function: One of the Image Capture Device Location Type Masks.
Notes: Mask to detect a device by another Macintosh host.
253
254
13.6.73
CHAPTER 13. IMAGE CAPTURE
ICDeviceLocationTypeShared = & h00000200
Plugin Version: 14.3. Function: One of the device types.
Notes: Device found over the network by searching for devices shared by other Macintosh hosts.
13.6.74
ICDeviceTypeCamera = & h00000001
Plugin Version: 14.3. Function: One of the image capture device types.
Notes: Camera device.
13.6.75
ICDeviceTypeMaskCamera = & h00000001
Plugin Version: 14.3. Function: One of the device type masks.
Notes: Mask to detect a camera device.
13.6.76
ICDeviceTypeMaskScanner = & h00000002
Plugin Version: 14.3. Function: One of the device type masks.
Notes: Mask to detect a scanner device.
13.6.77
ICDeviceTypeScanner = & h00000002
Plugin Version: 14.3. Function: One of the image capture device types.
Notes: Scanner device.
13.7. CLASS ICSCANNERBANDDATAMBS
13.7
class ICScannerBandDataMBS
13.7.1
class ICScannerBandDataMBS
255
Plugin Version: 14.3, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: The class for band
data from scanner.
Notes:
If image is too big to be transferred in one big block, it’s sent in little chunks using this class.
This is an abstract class. You can’t create an instance, but you can get one from various plugin functions.
13.7.2
Methods
13.7.3
Constructor
Plugin Version: 14.3, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: The private constructor.
13.7.4
Properties
13.7.5
bigEndian as Boolean
Plugin Version: 14.3, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: Describes if the
banded image data is reported in big endian.
Notes: (Read only property)
13.7.6
bitsPerComponent as UInt64
Plugin Version: 14.3, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: Describes the
number of bits per component for the banded image.
Notes: (Read only property)
13.7.7
bitsPerPixel as UInt64
Plugin Version: 14.3, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: Describes the
number of bits per pixel for banded the image.
Notes: (Read only property)
256
13.7.8
CHAPTER 13. IMAGE CAPTURE
bytesPerRow as UInt64
Plugin Version: 14.3, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: Descries how many
bytes are in each image band row.
Notes: (Read only property)
13.7.9
colorSyncProfilePath as String
Plugin Version: 14.3, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: Returns the path
to the color profile matching the banded data.
Notes: (Read only property)
13.7.10
dataBuffer as Memoryblock
Plugin Version: 14.3, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: The pointer to the
data buffer object.
Notes:
Plugin returns a copy of the data when you query this property.
(Read only property)
13.7.11
dataNumRows as UInt64
Plugin Version: 14.3, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: Describes the
number of rows contained in the image band.
Notes: (Read only property)
13.7.12
dataSize as UInt64
Plugin Version: 14.3, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: Describes the actual
data size of the image band buffer.
Notes: (Read only property)
13.7.13
dataStartRow as UInt64
Plugin Version: 14.3, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: Describes the start
row of the image band.
13.7. CLASS ICSCANNERBANDDATAMBS
257
Notes: (Read only property)
13.7.14
fullImageHeight as UInt64
Plugin Version: 14.3, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: Describes the full
image height of the banded image.
Notes: (Read only property)
13.7.15
fullImageWidth as UInt64
Plugin Version: 14.3, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: Describes the full
image width of the banded image.
Notes: (Read only property)
13.7.16
Handle as Integer
Plugin Version: 14.3, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: The internal object
reference.
Notes: (Read and Write property)
13.7.17
numComponents as UInt64
Plugin Version: 14.3, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: Describes how many
components are contained within the banded image.
Notes: (Read only property)
13.7.18
pixelDataType as Integer
Plugin Version: 14.3, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: Type of pixel data
that is contained in the band.
Notes:
See ICScannerFunctionalUnitMBS.ICScannerPixelDataType* constants.
(Read only property)
258
CHAPTER 13. IMAGE CAPTURE
13.8
class ICScannerDeviceMBS
13.8.1
class ICScannerDeviceMBS
Plugin Version: 14.3, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: The class for a
scanner device.
Notes:
ICScannerDeviceMBS is a concrete subclass of ICDeviceMBS class. ICDeviceBrowserMBS creates instances
of this class. In this release, an instance of ICScannerDeviceMBS class is intended to be used by the IKScannerDeviceViewMBS object. The IKScannerDeviceView class encapsulates the complexities of setting scan
parameters, performing scans and saving the result. The developer should consider using IKScannerDeviceViewMBS instead of building their own views using the ICScannerDeviceMBS object.
Subclass of the ICDeviceMBS class.
This is an abstract class. You can’t create an instance, but you can get one from various plugin functions.
13.8.2
Methods
13.8.3
availableFunctionalUnitTypes as Integer()
Plugin Version: 14.3, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: An array of functional unit types available on this scanner device.
Notes: This is an array of numbers whose values are of type ICScannerFunctionalUnitType.
13.8.4
cancelScan
Plugin Version: 14.3, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: Cancels the current
scan operation started by sending a ’requestOverviewScan’ or ’requestScan’.
13.8.5
Constructor
Plugin Version: 14.3, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: The private constructor.
13.8.6
ICScannerStatusRequestsOverviewScan as string
Plugin Version: 14.3, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: Constants used for
device status notifications.
Notes: A non-localized notification string to indicate that the scanner is requesting an overview scan to be
13.8. CLASS ICSCANNERDEVICEMBS
259
performed.
13.8.7
ICScannerStatusWarmingUp as string
Plugin Version: 14.3, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: Constants used for
device status notifications.
Notes: A non-localized notification string to indicate that the scanner is warming up.
13.8.8
ICScannerStatusWarmUpDone as string
Plugin Version: 14.3, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: Constants used for
device status notifications.
Notes: A non-localized notification string to indicate that the scanner has warmed up.
13.8.9
requestOverviewScan
Plugin Version: 14.3, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: Starts an overview
scan on selectedFunctionalUnit.
Notes: When this request is completed, the delegate will be notified using the scannerDeviceDidCompleteOverviewScanWithError event. The content of error returned should be examined to determine if the
request completed successfully.
13.8.10
requestScan
Plugin Version: 14.3, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: Starts a scan on
selectedFunctionalUnit.
Notes: When this request is completed, the delegate will be notified using the scannerDeviceDidCompleteScanWithError event. The content of error returned should be examined to determine if the request completed
successfully.
13.8.11
requestSelectFunctionalUnit(type as Integer)
Plugin Version: 14.3, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: Requests the
scanner device to select a functional unit.
Notes: When this request is completed, the delegate will be notified using the scannerDeviceDidSelectFunctionalUnit.
260
CHAPTER 13. IMAGE CAPTURE
13.8.12
Properties
13.8.13
documentName as String
Plugin Version: 14.3, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: The document
name.
Notes: (Read and Write property)
13.8.14
documentUTI as String
Plugin Version: 14.3, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: The document UTI.
Notes:
Currently supported UTIs are: kUTTypeJPEG, kUTTypeJPEG2000, kUTTypeTIFF, kUTTypePNG etc.
see UTTypeMBS module.
(Read and Write property)
13.8.15
downloadsDirectory as String
Plugin Version: 14.3, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: The downloads
directory.
Notes:
Download location can be provided as file URL with downloadsDirectory property or as folderitem with
downloadsFolder property.
(Read and Write property)
13.8.16
downloadsFolder as FolderItem
Plugin Version: 14.3, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: The downloads
directory.
Notes:
Download location can be provided as file URL with downloadsDirectory property or as folderitem with
downloadsFolder property.
(Read and Write property)
13.8.17
maxMemoryBandSize as UInt64
Plugin Version: 14.3, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: The total maximum
band size requested when performing a ICScannerTransferModeMemoryBased.
13.8. CLASS ICSCANNERDEVICEMBS
261
Notes: (Read and Write property)
13.8.18
selectedFunctionalUnit as ICScannerFunctionalUnitMBS
Plugin Version: 14.3, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: The currently
selected functional unit on the scanner device.
Notes: (Read only property)
13.8.19
transferMode as Integer
Plugin Version: 14.3, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: The transfer mode
for scanned document.
Notes: (Read and Write property)
13.8.20
Constants
13.8.21
ICScannerTransferModeFileBased = 0
Plugin Version: 14.3. Function: Transfer mode constants to be used when transferring scan data from the
scanner functional unit.
Notes: Save the scan as a file.
13.8.22
ICScannerTransferModeMemoryBased = 1
Plugin Version: 14.3. Function: Transfer mode constants to be used when transferring scan data from the
scanner functional unit.
Notes: Transfer the scan as data.
262
CHAPTER 13. IMAGE CAPTURE
13.9
class ICScannerFeatureBooleanMBS
13.9.1
class ICScannerFeatureBooleanMBS
Plugin Version: 14.3, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: ICScannerFeatureBoolean object is used to represent a property of a scanner functional unit whose value can be true or false.
Notes:
Subclass of the ICScannerFeatureMBS class.
This is an abstract class. You can’t create an instance, but you can get one from various plugin functions.
13.9.2
Methods
13.9.3
Constructor
Plugin Version: 14.3, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: The private constructor.
13.9.4
Properties
13.9.5
value as Boolean
Plugin Version: 14.3, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: The value of this
feature.
Notes: (Read and Write property)
13.10. CLASS ICSCANNERFEATUREENUMERATIONMBS
13.10
class ICScannerFeatureEnumerationMBS
13.10.1
class ICScannerFeatureEnumerationMBS
263
Plugin Version: 14.3, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: ICScannerFeatureEnumeration object is used to represent a feature of a scanner functional unit that can have one of
several discrete values.
Notes:
Subclass of the ICScannerFeatureMBS class.
This is an abstract class. You can’t create an instance, but you can get one from various plugin functions.
13.10.2
Methods
13.10.3
Constructor
Plugin Version: 14.3, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: The private constructor.
13.10.4
menuItemLabels as String()
Plugin Version: 14.3, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: The human readable
menu item labels to be used in a menu to allow the user to select the current value from an array of possible
values.
13.10.5
menuItemLabelsTooltips as String()
Plugin Version: 14.3, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: Tooltip text associated with the menu items.
13.10.6
values as Variant()
Plugin Version: 14.3, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: An array of possible
values. All items in this array must be of same type.
264
CHAPTER 13. IMAGE CAPTURE
13.10.7
Properties
13.10.8
currentValue as Variant
Plugin Version: 14.3, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: The current value.
Notes:
The current value can be set to one of the possible values in the ”values” property below.
(Read and Write property)
13.10.9
defaultValue as Variant
Plugin Version: 14.3, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: The default value.
Notes:
The default value can be set to one of the possible values in the ”values” property below.
(Read only property)
13.11. CLASS ICSCANNERFEATUREMBS
13.11
class ICScannerFeatureMBS
13.11.1
class ICScannerFeatureMBS
265
Plugin Version: 14.3, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: ICScannerFeature
class is an abstract base class used to describe a scanner feature.
Notes:
ImageCaptureCore defines three concrete subclasses of ICScannerFeatureMBS: ICScannerFeatureEnumerationMBS, ICScannerFeatureRangeMBS and ICScannerFeatureBooleanMBS.
The scanner functional units may have one or more instances of these classes to allow users to choose scannerspecific settings or operations before performing a scan.
This is an abstract class. You can’t create an instance, but you can get one from various plugin functions.
13.11.2
Methods
13.11.3
Constructor
Plugin Version: 14.3, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: The private constructor.
13.11.4
Properties
13.11.5
Handle as Integer
Plugin Version: 14.3, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: The internal object
reference.
Notes: (Read and Write property)
13.11.6
humanReadableName as String
Plugin Version: 14.3, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: The human readable
name of this feature.
Notes: (Read only property)
13.11.7
internalName as String
Plugin Version: 14.3, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: The internal name
of this feature.
266
CHAPTER 13. IMAGE CAPTURE
Notes: (Read only property)
13.11.8
tooltip as String
Plugin Version: 14.3, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: Tooltip text describing the feature.
Notes: (Read only property)
13.11.9
type as Integer
Plugin Version: 14.3, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: Scanner feature
type.
Notes:
See ICScannerFeatureType* constants.
(Read only property)
13.11.10
Constants
13.11.11
ICScannerFeatureTypeBoolean = 2
Plugin Version: 14.3. Function: One of the feature type constants.
Notes: The value of this feature can be true or false.
13.11.12
ICScannerFeatureTypeEnumeration = 0
Plugin Version: 14.3. Function: One of the feature type constants.
Notes: This feature can have one of several discrete values, strings or numbers.
13.11.13
ICScannerFeatureTypeRange = 1
Plugin Version: 14.3. Function: One of the feature type constants.
Notes: This value of this feature lies within a range.
13.11. CLASS ICSCANNERFEATUREMBS
13.11.14
ICScannerFeatureTypeTemplate = 3
Plugin Version: 14.3. Function: One of the feature type constants.
Notes: A group of features.
267
268
CHAPTER 13. IMAGE CAPTURE
13.12
class ICScannerFeatureRangeMBS
13.12.1
class ICScannerFeatureRangeMBS
Plugin Version: 14.3, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: ICScannerFeatureRange object is used to represent a property of a scanner functional unit whose value lies within a range.
Notes:
Subclass of the ICScannerFeatureMBS class.
This is an abstract class. You can’t create an instance, but you can get one from various plugin functions.
13.12.2
Methods
13.12.3
Constructor
Plugin Version: 14.3, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: The private constructor.
13.12.4
Properties
13.12.5
currentValue as Double
Plugin Version: 14.3, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: The current value.
Notes:
Attempting to set the current value to a value that is not coincident with a step will result in a value corresponding to the nearest step being assigned to the current value.
(Read only property)
13.12.6
defaultValue as Double
Plugin Version: 14.3, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: The default value.
Notes:
Attempting to set the default value to a value that is not coincident with a step will result in a value corresponding to the nearest step being assigned to the default value.
(Read only property)
13.12. CLASS ICSCANNERFEATURERANGEMBS
13.12.7
269
maxValue as Double
Plugin Version: 14.3, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: The maximum
value.
Notes: (Read only property)
13.12.8
minValue as Double
Plugin Version: 14.3, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: The minimum
value.
Notes: (Read only property)
13.12.9
stepSize as Double
Plugin Version: 14.3, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: The step size.
Notes: (Read only property)
270
CHAPTER 13. IMAGE CAPTURE
13.13
class ICScannerFeatureTemplateMBS
13.13.1
class ICScannerFeatureTemplateMBS
Plugin Version: 14.3, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: ICScannerFeatureTemplate object is used to define a group of one or more rectangular scan areas that can be used with
a scanner functional unit.
Notes:
Subclass of the ICScannerFeatureMBS class.
This is an abstract class. You can’t create an instance, but you can get one from various plugin functions.
13.13.2
Methods
13.13.3
Constructor
Plugin Version: 14.3, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: The private constructor.
13.13.4
targets as ICScannerFeatureMBS()
Plugin Version: 14.3, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: The target features.
13.14. CLASS ICSCANNERFUNCTIONALUNITDOCUMENTFEEDERMBS
13.14
class ICScannerFunctionalUnitDocumentFeederMBS
13.14.1
class ICScannerFunctionalUnitDocumentFeederMBS
271
Plugin Version: 14.3, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: ICScannerFunctionalUnitDocumentFeeder is a concrete subclass of ICScannerFunctionalUnit class.
Notes:
ICScannerDevice creates instances of this class.
This represents the document feeder unit on the scanner.
Subclass of the ICScannerFunctionalUnitMBS class.
This is an abstract class. You can’t create an instance, but you can get one from various plugin functions.
13.14.2
Methods
13.14.3
Constructor
Plugin Version: 14.3, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: The private constructor.
13.14.4
Properties
13.14.5
documentLoaded as Boolean
Plugin Version: 14.3, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: Indicates whether
the feeder has documents to scan.
Notes:
This value will change when the document is loaded or removed from the feeder, if the scanner module has
the capability to detect this state.
(Read only property)
13.14.6
duplexScanningEnabled as Boolean
Plugin Version: 14.3, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: Indicates whether
duplex scanning is enabled.
Notes: (Read and Write property)
272
13.14.7
CHAPTER 13. IMAGE CAPTURE
evenPageOrientation as Integer
Plugin Version: 14.3, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: Desired orientation
of the even pages of the scanned document.
Notes:
This property is set to ICEXIFOrientation1 initially.
Possible values:
ICEXIFOrientation1
ICEXIFOrientation2
ICEXIFOrientation3
ICEXIFOrientation4
ICEXIFOrientation5
ICEXIFOrientation6
ICEXIFOrientation7
ICEXIFOrientation8
1
2
3
4
5
6
7
8
Normal
Flipped horizontally
Rotated 180
Flipped vertically
Rotated 90 CCW and flipped vertically
Rotated 90 CCW
Rotated 90 CW and flipped vertically
Rotated 90 CW
(Read and Write property)
13.14.8
oddPageOrientation as Integer
Plugin Version: 14.3, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: Desired orientation
of the odd pages of the scanned document.
Notes:
This property is set to ICEXIFOrientation1 initially.
Possible values:
ICEXIFOrientation1
ICEXIFOrientation2
ICEXIFOrientation3
ICEXIFOrientation4
ICEXIFOrientation5
ICEXIFOrientation6
ICEXIFOrientation7
ICEXIFOrientation8
1
2
3
4
5
6
7
8
(Read and Write property)
Normal
Flipped horizontally
Rotated 180
Flipped vertically
Rotated 90 CCW and flipped vertically
Rotated 90 CCW
Rotated 90 CW and flipped vertically
Rotated 90 CW
13.14. CLASS ICSCANNERFUNCTIONALUNITDOCUMENTFEEDERMBS
13.14.9
273
reverseFeederPageOrder as Boolean
Plugin Version: 14.3, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: Indicates whether
the document feeder reads pages from back to front.
Notes: (Read only property)
13.14.10
supportsDuplexScanning as Boolean
Plugin Version: 14.3, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: Indicates whether
duplex scanning is supported.
Notes: (Read only property)
274
CHAPTER 13. IMAGE CAPTURE
13.15
class ICScannerFunctionalUnitFlatbedMBS
13.15.1
class ICScannerFunctionalUnitFlatbedMBS
Plugin Version: 14.3, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: ICScannerFunctionalUnitFlatbedMBS is a concrete subclass of ICScannerFunctionalUnitMBS class.
Notes:
ICScannerDevice creates instances of this class.
This represents the flatbed unit on the scanner.
Subclass of the ICScannerFunctionalUnitMBS class.
This is an abstract class. You can’t create an instance, but you can get one from various plugin functions.
13.15.2
Methods
13.15.3
Constructor
Plugin Version: 14.3, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: The private constructor.
13.16. CLASS ICSCANNERFUNCTIONALUNITMBS
13.16
class ICScannerFunctionalUnitMBS
13.16.1
class ICScannerFunctionalUnitMBS
275
Plugin Version: 14.3, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: ICScannerFunctionalUnit is an abstract class that represents a scanner functiona unit.
Notes:
ImageCaptureCore defines three concrete subclasses of ICScannerFunctionalUnit: ICScannerFunctionalUnitFlatbed, ICScannerFunctionalUnitPositiveTransparency, ICScannerFunctionalUnitNegativeTransparency
and ICScannerFunctionalUnitDocumentFeeder. ICScannerDevice creates instances of these concrete subclasses.
This is an abstract class. You can’t create an instance, but you can get one from various plugin functions.
13.16.2
Methods
13.16.3
Constructor
Plugin Version: 14.3, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: The private constructor.
13.16.4
templates as ICScannerFeatureTemplateMBS()
Plugin Version: 14.3, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: An array of objects
of type ICScannerFeatureTemplate.
13.16.5
vendorFeatures as ICScannerFeatureMBS()
Plugin Version: 14.3, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: An array of objects
of type ICScannerFeature.
13.16.6
Properties
13.16.7
acceptsThresholdForBlackAndWhiteScanning as Boolean
Plugin Version: 14.3, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: Indicates if this
functional unit accepts threshold value to be used when performing a scan in black & white.
Notes: (Read only property)
276
13.16.8
CHAPTER 13. IMAGE CAPTURE
bitDepth as Integer
Plugin Version: 14.3, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: The bit depth to
use when performing the final scan.
Notes:
This will always be one of the supported bit depths.
(Read and Write property)
13.16.9
canPerformOverviewScan as Boolean
Plugin Version: 14.3, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: Indicates if this
functional unit can perfrom an overview scan.
Notes:
Not all functional units can perform an overview scan. For example, a document feeder or a sheet feeder
unit cannot perform an overview scan.
(Read only property)
13.16.10
defaultThresholdForBlackAndWhiteScanning as Integer
Plugin Version: 14.3, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: Default threshold
value used when performing a scan in black & white.
Notes:
This value is from 0 to 255.
(Read only property)
13.16.11
documentSize as NSSizeMBS
Plugin Version: 14.3, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: Document size of
the current document type expressed in current measurement unit.
Notes: (Read only property)
13.16.12
documentType as Integer
Plugin Version: 14.3, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: Current document
type.
Notes:
This will always be one of the supported document types.
13.16. CLASS ICSCANNERFUNCTIONALUNITMBS
277
(Read and Write property)
13.16.13
measurementUnit as Integer
Plugin Version: 14.3, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: Current measurement unit. This will always be one of the supported measurement units.
Notes: (Read and Write property)
13.16.14
nativeXResolution as Integer
Plugin Version: 14.3, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: Optical resolution
along the X axis.
Notes: (Read only property)
13.16.15
nativeYResolution as Integer
Plugin Version: 14.3, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: Optical resolution
along the Y axis.
Notes: (Read only property)
13.16.16
overviewImage as Variant
Plugin Version: 14.3, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: Overview scan
image.
Notes:
This property will be nil for functional units that do not support overview scans.
Value is a CGImageMBS.
(Read only property)
13.16.17
overviewResolution as Integer
Plugin Version: 14.3, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: Overview image
resolution.
Notes:
Value assigned to this will be contrained by resolutions allowed by the device.
(Read and Write property)
278
13.16.18
CHAPTER 13. IMAGE CAPTURE
overviewScanInProgress as Boolean
Plugin Version: 14.3, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: Indicates if an
overview scan is in progress.
Notes: (Read only property)
13.16.19
physicalSize as NSSizeMBS
Plugin Version: 14.3, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: Physical size of the
scan area in current measurement unit.
Notes: (Read only property)
13.16.20
pixelDataType as Integer
Plugin Version: 14.3, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: The pixel data type.
Notes:
See ICScannerPixelDataType* constants.
(Read and Write property)
13.16.21
preferredResolutions as NSIndexSetMBS
Plugin Version: 14.3, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: Current scan
resolution.
Notes:
This will always be one of the supported resolution values.
(Read only property)
13.16.22
preferredScaleFactors as NSIndexSetMBS
Plugin Version: 14.3, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: Preferred scale
factors in percentage.
Notes: (Read only property)
13.16. CLASS ICSCANNERFUNCTIONALUNITMBS
13.16.23
279
resolution as Integer
Plugin Version: 14.3, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: Current scan
resolution.
Notes:
This will always be one of the supported resolution values.
(Read and Write property)
13.16.24
scaleFactor as Integer
Plugin Version: 14.3, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: Current scale factor.
Notes:
This will always be one of the supported scale factor values.
(Read only property)
13.16.25
scanArea as NSRectMBS
Plugin Version: 14.3, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: This property along
with scanAreaOrientation describes the area to be scanned.
Notes: (Read and Write property)
13.16.26
scanAreaOrientation as Integer
Plugin Version: 14.3, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: Desired orientation
of the scan area.
Notes:
This property along with scanArea describes the area to be scanned.
This property is set to ICEXIFOrientation1 initially. This property is not used by the ICScannerFunctionalUnitDocumentFeeder subclass.
Possible values:
(Read and Write property)
280
CHAPTER 13. IMAGE CAPTURE
ICEXIFOrientation1
ICEXIFOrientation2
ICEXIFOrientation3
ICEXIFOrientation4
ICEXIFOrientation5
ICEXIFOrientation6
ICEXIFOrientation7
ICEXIFOrientation8
13.16.27
1
2
3
4
5
6
7
8
Normal
Flipped horizontally
Rotated 180
Flipped vertically
Rotated 90 CCW and flipped vertically
Rotated 90 CCW
Rotated 90 CW and flipped vertically
Rotated 90 CW
scanInProgress as Boolean
Plugin Version: 14.3, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: Indicates if a scan
is in progress.
Notes: (Read only property)
13.16.28
scanProgressPercentDone as Double
Plugin Version: 14.3, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: Indicates percentage
of scan completed.
Notes: (Read only property)
13.16.29
state as Integer
Plugin Version: 14.3, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: Indicates the current
state of the functional unit.
Notes:
See ICScannerFunctionalUnitState* constants.
(Read only property)
13.16.30
supportedBitDepths as NSIndexSetMBS
Plugin Version: 14.3, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: Supported bit
depths.
Notes:
The values in this set are valid values defined by ICScannerBitDepth.
(Read only property)
13.16. CLASS ICSCANNERFUNCTIONALUNITMBS
13.16.31
281
supportedDocumentTypes as NSIndexSetMBS
Plugin Version: 14.3, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: Supported document
types.
Notes:
The values in this set are valid values defined by ICScannerDocumentType.
(Read only property)
13.16.32
supportedMeasurementUnits as NSIndexSetMBS
Plugin Version: 14.3, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: Supported measurement units. The values in this set are valid values defined by ICScannerMeasurementUnit.
Notes: (Read only property)
13.16.33
supportedResolutions as NSIndexSetMBS
Plugin Version: 14.3, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: Supported scan
resolutions in DPI.
Notes: (Read only property)
13.16.34
supportedScaleFactors as NSIndexSetMBS
Plugin Version: 14.3, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: Supported scale
factors in percentage.
Notes: (Read only property)
13.16.35
thresholdForBlackAndWhiteScanning as Integer
Plugin Version: 14.3, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: Threshold value to
be used when performing a scan in black & white.
Notes:
This value should be from 0 to 255.
(Read and Write property)
282
13.16.36
CHAPTER 13. IMAGE CAPTURE
type as Integer
Plugin Version: 14.3, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: Functional unit
type.
Notes:
See ICScannerFunctionalUnitType* constants.
(Read only property)
13.16.37
usesThresholdForBlackAndWhiteScanning as Boolean
Plugin Version: 14.3, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: Indicates if this
functional unit uses threshold value to be used when performing a scan in black & white.
Notes: (Read only property)
13.16.38
Constants
13.16.39
ICScannerBitDepth16Bits = 16
Plugin Version: 14.3. Function: One of the possible number of bits per channel in the scanned image.
Notes: Image with 16 bits per channel.
13.16.40
ICScannerBitDepth1Bit = 1
Plugin Version: 14.3. Function: One of the possible number of bits per channel in the scanned image.
Notes: 1-bit image.
13.16.41
ICScannerBitDepth8Bits = 8
Plugin Version: 14.3. Function: One of the possible number of bits per channel in the scanned image.
Notes: Image with 8 bits per channel.
13.16.42
ICScannerColorDataFormatTypeChunky = 0
Plugin Version: 14.3. Function: One of the color data formats.
Notes:
13.16. CLASS ICSCANNERFUNCTIONALUNITMBS
283
For multi-channel data (e.g., RGB) data from all channels are interleaved.
Identifies color data formats. Only relevant for multi-channel data. Corresponds to ”ICAP PLANARCHUNKY”
of the TWAIN Specification.
13.16.43
ICScannerColorDataFormatTypePlanar = 1
Plugin Version: 14.3. Function: One of the color data formats.
Notes:
For multi-channel data (e.g., RGB) each channel is transferred sequentially.
Identifies color data formats. Only relevant for multi-channel data. Corresponds to ”ICAP PLANARCHUNKY”
of the TWAIN Specification.
13.16.44
ICScannerDocumentType10 = 25
Plugin Version: 14.3. Function: One of the document types.
Notes: A10, 26.00 mm x 37.00 mm
13.16.45
ICScannerDocumentType10R = 67
Plugin Version: 14.3. Function: One of the document types.
Notes: 10R, 10” x 12” 254.00 mm x 304.80 mm 5:6
13.16.46
ICScannerDocumentType110 = 72
Plugin Version: 14.3. Function: One of the document types.
Notes: Instamatic 110, 13.00 mm x 17.00 mm
13.16.47
ICScannerDocumentType11R = 69
Plugin Version: 14.3. Function: One of the document types.
Notes: 11R, 11” x 14” 279.40 mm x 355.60 mm 11:14
284
13.16.48
CHAPTER 13. IMAGE CAPTURE
ICScannerDocumentType12R = 70
Plugin Version: 14.3. Function: One of the document types.
Notes: 12R, 12” x 15” 304.80 mm x 381.00 mm 4:5
13.16.49
ICScannerDocumentType135 = 76
Plugin Version: 14.3. Function: One of the document types.
Notes: Standard 35 mm, 36.00 mm x 24.00 mm
13.16.50
ICScannerDocumentType2A0 = 18
Plugin Version: 14.3. Function: One of the document types.
Notes: 2A0, 1189.00 mm x 1682.00 mm
13.16.51
ICScannerDocumentType3R = 61
Plugin Version: 14.3. Function: One of the document types.
Notes: 3R, 3.5” x 5” 88.90 mm x 127.00 mm 7:10
13.16.52
ICScannerDocumentType4A0 = 17
Plugin Version: 14.3. Function: One of the document types.
Notes: 4A0, 1682.00 mm x 2378.00 mm
13.16.53
ICScannerDocumentType4R = 62
Plugin Version: 14.3. Function: One of the document types.
Notes: 4R, 4” x 6” 101.60 mm x 152.40 mm 2:3
13.16.54
ICScannerDocumentType5R = 63
Plugin Version: 14.3. Function: One of the document types.
Notes: 5R, 5” x 7” 127.00 mm x 177.80 mm 5:7
13.16. CLASS ICSCANNERFUNCTIONALUNITMBS
13.16.55
ICScannerDocumentType6R = 64
Plugin Version: 14.3. Function: One of the document types.
Notes: 6R, 6” x 8” 152.40 mm x 203.20 mm 3:4
13.16.56
ICScannerDocumentType8R = 65
Plugin Version: 14.3. Function: One of the document types.
Notes: 8R, 8” x 10” 203.20 mm x 254.00 mm 4:5
13.16.57
ICScannerDocumentTypeA0 = 19
Plugin Version: 14.3. Function: One of the document types.
Notes: A0, 841.00 mm x 1189.00 mm
13.16.58
ICScannerDocumentTypeA1 = 20
Plugin Version: 14.3. Function: One of the document types.
Notes: A1, 594.00 mm x 841.00 mm
13.16.59
ICScannerDocumentTypeA2 = 21
Plugin Version: 14.3. Function: One of the document types.
Notes: A2, 420.00 mm x 594.00 mm
13.16.60
ICScannerDocumentTypeA3 = 11
Plugin Version: 14.3. Function: One of the document types.
Notes: A3, 297.00 mm x 420.00 mm
13.16.61
ICScannerDocumentTypeA4 = 1
Plugin Version: 14.3. Function: One of the document types.
Notes: A4, 210.00 mm x 297.00 mm
285
286
13.16.62
CHAPTER 13. IMAGE CAPTURE
ICScannerDocumentTypeA5 = 5
Plugin Version: 14.3. Function: One of the document types.
Notes: A5, 148.00 mm x 210.00 mm
13.16.63
ICScannerDocumentTypeA6 = 13
Plugin Version: 14.3. Function: One of the document types.
Notes: A6, 105.00 mm x 148.00 mm
13.16.64
ICScannerDocumentTypeA7 = 22
Plugin Version: 14.3. Function: One of the document types.
Notes: A7, 74.00 mm x 105.00 mm
13.16.65
ICScannerDocumentTypeA8 = 23
Plugin Version: 14.3. Function: One of the document types.
Notes: A8, 52.00 mm x 74.00 mm
13.16.66
ICScannerDocumentTypeA9 = 24
Plugin Version: 14.3. Function: One of the document types.
Notes: A9, 37.00 mm x 52.00 mm
13.16.67
ICScannerDocumentTypeAPSC = 74
Plugin Version: 14.3. Function: One of the document types.
Notes: APS Classic, 25.10 mm x 16.70 mm
13.16.68
ICScannerDocumentTypeAPSH = 73
Plugin Version: 14.3. Function: One of the document types.
Notes: APS High Definition, 30.20 mm x 16.70 mm
13.16. CLASS ICSCANNERFUNCTIONALUNITMBS
13.16.69
ICScannerDocumentTypeAPSP = 75
Plugin Version: 14.3. Function: One of the document types.
Notes: APS Panoramic, 30.20 mm x 9.50 mm
13.16.70
ICScannerDocumentTypeB5 = 2
Plugin Version: 14.3. Function: One of the document types.
Notes: B5/JIS B5, 182.00 mm x 257.00 mm
13.16.71
ICScannerDocumentTypeBusinessCard = 53
Plugin Version: 14.3. Function: One of the document types.
Notes: Business Card, 90.00 mm x 55.00 mm
13.16.72
ICScannerDocumentTypeC0 = 44
Plugin Version: 14.3. Function: One of the document types.
Notes: C0, 917.00 mm x 1297.00 mm
13.16.73
ICScannerDocumentTypeC1 = 45
Plugin Version: 14.3. Function: One of the document types.
Notes: C1, 648.00 mm x 917.00 mm
13.16.74
ICScannerDocumentTypeC10 = 51
Plugin Version: 14.3. Function: One of the document types.
Notes: C10, 28.00 mm x 40.00 mm
13.16.75
ICScannerDocumentTypeC2 = 46
Plugin Version: 14.3. Function: One of the document types.
Notes: C2, 458.00 mm x 648.00 mm
287
288
13.16.76
CHAPTER 13. IMAGE CAPTURE
ICScannerDocumentTypeC3 = 47
Plugin Version: 14.3. Function: One of the document types.
Notes: C3, 324.00 mm x 458.00 mm
13.16.77
ICScannerDocumentTypeC4 = 14
Plugin Version: 14.3. Function: One of the document types.
Notes: C4, 229.00 mm x 324.00 mm
13.16.78
ICScannerDocumentTypeC5 = 15
Plugin Version: 14.3. Function: One of the document types.
Notes: C5, 162.00 mm x 229.00 mm
13.16.79
ICScannerDocumentTypeC6 = 16
Plugin Version: 14.3. Function: One of the document types.
Notes: C6, 114.00 mm x 162.00 mm
13.16.80
ICScannerDocumentTypeC7 = 48
Plugin Version: 14.3. Function: One of the document types.
Notes: C7, 81.00 mm x 114.00 mm
13.16.81
ICScannerDocumentTypeC8 = 49
Plugin Version: 14.3. Function: One of the document types.
Notes: C8, 57.00 mm x 81.00 mm
13.16.82
ICScannerDocumentTypeC9 = 50
Plugin Version: 14.3. Function: One of the document types.
Notes: C9, 40.00 mm x 57.00 mm
13.16. CLASS ICSCANNERFUNCTIONALUNITMBS
13.16.83
ICScannerDocumentTypeDefault = 0
Plugin Version: 14.3. Function: One of the document types.
Notes: This is the platten size. Not valid for scanners without a platten.
13.16.84
ICScannerDocumentTypeE = 60
Plugin Version: 14.3. Function: One of the document types.
Notes: Japanese E, 3.25” x 4.75” 82.55 mm x 120.65 mm 11:16
13.16.85
ICScannerDocumentTypeISOB0 = 26
Plugin Version: 14.3. Function: One of the document types.
Notes: ISO B0, 1000.00 mm x 1414.00 mm
13.16.86
ICScannerDocumentTypeISOB1 = 27
Plugin Version: 14.3. Function: One of the document types.
Notes: ISO B1, 707.00 mm x 1000.00 mm
13.16.87
ICScannerDocumentTypeISOB10 = 33
Plugin Version: 14.3. Function: One of the document types.
Notes: ISO B10, 31.00 mm x 44.00 mm
13.16.88
ICScannerDocumentTypeISOB2 = 28
Plugin Version: 14.3. Function: One of the document types.
Notes: ISO B2, 500.00 mm x 707.00 mm
13.16.89
ICScannerDocumentTypeISOB3 = 12
Plugin Version: 14.3. Function: One of the document types.
Notes: B3/ISO B3, 353.00 mm x 500.00 mm
289
290
13.16.90
CHAPTER 13. IMAGE CAPTURE
ICScannerDocumentTypeISOB4 = 6
Plugin Version: 14.3. Function: One of the document types.
Notes: B4/ISO B4, 250.00 mm x 353.00 mm
13.16.91
ICScannerDocumentTypeISOB5 = 29
Plugin Version: 14.3. Function: One of the document types.
Notes: ISO B5, 176.00 mm x 250.00 mm
13.16.92
ICScannerDocumentTypeISOB6 = 7
Plugin Version: 14.3. Function: One of the document types.
Notes: B6/ISO B6, 125.00 mm x 176.00 mm
13.16.93
ICScannerDocumentTypeISOB7 = 30
Plugin Version: 14.3. Function: One of the document types.
Notes: ISO B7, 88.00 mm x 125.00 mm
13.16.94
ICScannerDocumentTypeISOB8 = 31
Plugin Version: 14.3. Function: One of the document types.
Notes: ISO B8, 62.00 mm x 88.00 mm
13.16.95
ICScannerDocumentTypeISOB9 = 32
Plugin Version: 14.3. Function: One of the document types.
Notes: ISO B9, 44.00 mm x 62.00 mm
13.16.96
ICScannerDocumentTypeJISB0 = 34
Plugin Version: 14.3. Function: One of the document types.
Notes: JIS B0, 1030.00 mm x 1456.00 mm
13.16. CLASS ICSCANNERFUNCTIONALUNITMBS
13.16.97
ICScannerDocumentTypeJISB1 = 35
Plugin Version: 14.3. Function: One of the document types.
Notes: JIS B1, 728.00 mm x 1030.00 mm
13.16.98
ICScannerDocumentTypeJISB10 = 43
Plugin Version: 14.3. Function: One of the document types.
Notes: JIS B10, 32.00 mm x 45.00 mm
13.16.99
ICScannerDocumentTypeJISB2 = 36
Plugin Version: 14.3. Function: One of the document types.
Notes: JIS B2, 515.00 mm x 728.00 mm
13.16.100
ICScannerDocumentTypeJISB3 = 37
Plugin Version: 14.3. Function: One of the document types.
Notes: JIS B3, 364.00 mm x 515.00 mm
13.16.101
ICScannerDocumentTypeJISB4 = 38
Plugin Version: 14.3. Function: One of the document types.
Notes: JIS B4, 257.00 mm x 364.00 mm
13.16.102
ICScannerDocumentTypeJISB6 = 39
Plugin Version: 14.3. Function: One of the document types.
Notes: JIS B6, 128.00 mm x 182.00 mm
13.16.103
ICScannerDocumentTypeJISB7 = 40
Plugin Version: 14.3. Function: One of the document types.
Notes: JIS B7, 91.00 mm x 128.00 mm
291
292
13.16.104
CHAPTER 13. IMAGE CAPTURE
ICScannerDocumentTypeJISB8 = 41
Plugin Version: 14.3. Function: One of the document types.
Notes: JIS B8, 64.00 mm x 91.00 mm
13.16. CLASS ICSCANNERFUNCTIONALUNITMBS
13.16.105
ICScannerDocumentTypeJISB9 = 42
Plugin Version: 14.3. Function: One of the document types.
Notes: JIS B9, 45.00 mm x 64.00 mm
13.16.106
ICScannerDocumentTypeLF = 78
Plugin Version: 14.3. Function: One of the document types.
Notes: Large Format, 100.00 mm x 120.00 mm
13.16.107
ICScannerDocumentTypeMF = 77
Plugin Version: 14.3. Function: One of the document types.
Notes: Medium Format, 60.00 mm x 60.00 mm
13.16.108
ICScannerDocumentTypeS10R = 68
Plugin Version: 14.3. Function: One of the document types.
Notes: S10R, 10” x 15” 254.00 mm x 381.00 mm 2:3
13.16.109
ICScannerDocumentTypeS12R = 71
Plugin Version: 14.3. Function: One of the document types.
Notes: S12R, 12” x 18” 304.80 mm x 457.20 mm 2:3
13.16.110
ICScannerDocumentTypeS8R = 66
Plugin Version: 14.3. Function: One of the document types.
Notes: S8R 8” x 12” 203.20 mm x 304.80 mm 2:3
13.16.111
ICScannerDocumentTypeUSExecutive = 10
Plugin Version: 14.3. Function: One of the document types.
Notes: US Executive, 7.25” x 10.5”, 184.15 mm x 266.70 mm
293
294
13.16.112
CHAPTER 13. IMAGE CAPTURE
ICScannerDocumentTypeUSLedger = 9
Plugin Version: 14.3. Function: One of the document types.
Notes: US Ledger, 11” x 17.0”, 279.40 mm x 431.80 mm
13.16.113
ICScannerDocumentTypeUSLegal = 4
Plugin Version: 14.3. Function: One of the document types.
Notes: US Legal, 8.5” x 14.0”, 215.90 mm x 355.60 mm
13.16.114
ICScannerDocumentTypeUSLetter = 3
Plugin Version: 14.3. Function: One of the document types.
Notes: US Letter, 8.5” x 11.0”, 215.90 mm x 279.40 mm
13.16.115
ICScannerDocumentTypeUSStatement = 52
Plugin Version: 14.3. Function: One of the document types.
Notes: US Statement, 5.5” x 8.5”, 139.70 mm x 215.90 mm
13.16.116
ICScannerFunctionalUnitStateOverviewScanInProgress = 4
Plugin Version: 14.3. Function: A flag to indicate the scanner functional unit’s state.
Notes: The scanner functional unit is performing an overview scan.
13.16.117
ICScannerFunctionalUnitStateReady = 1
Plugin Version: 14.3. Function: A flag to indicate the scanner functional unit’s state.
Notes: The scanner functional unit is ready for operation.
13.16.118
ICScannerFunctionalUnitStateScanInProgress = 2
Plugin Version: 14.3. Function: A flag to indicate the scanner functional unit’s state.
Notes: The scanner functional unit is performing a scan.
13.16. CLASS ICSCANNERFUNCTIONALUNITMBS
13.16.119
ICScannerFunctionalUnitTypeDocumentFeeder = 3
Plugin Version: 14.3. Function: One of the Scanner Functional Unit Types.
Notes: Document feeder functional unit.
13.16.120
ICScannerFunctionalUnitTypeFlatbed = 0
Plugin Version: 14.3. Function: One of the Scanner Functional Unit Types.
Notes: Flatbed functional unit.
13.16.121
ICScannerFunctionalUnitTypeNegativeTransparency = 2
Plugin Version: 14.3. Function: One of the Scanner Functional Unit Types.
Notes: Transparency functional unit for scanning negatives.
13.16.122
ICScannerFunctionalUnitTypePositiveTransparency = 1
Plugin Version: 14.3. Function: One of the Scanner Functional Unit Types.
Notes: Transparency functional unit for scanning positives.
13.16.123
ICScannerMeasurementUnitCentimeters = 1
Plugin Version: 14.3. Function: One of the units of measurement used by the scanner.
Notes: 1 cm = 1.00 cm or 1/2.54 inches
13.16.124
ICScannerMeasurementUnitInches = 0
Plugin Version: 14.3. Function: One of the units of measurement used by the scanner.
Notes: 1 inch = 2.54 cm
13.16.125
ICScannerMeasurementUnitPicas = 2
Plugin Version: 14.3. Function: One of the units of measurement used by the scanner.
Notes: 1 pica = .42333333 cm or 1/6 inches
295
296
13.16.126
CHAPTER 13. IMAGE CAPTURE
ICScannerMeasurementUnitPixels = 5
Plugin Version: 14.3. Function: One of the units of measurement used by the scanner.
13.16.127
ICScannerMeasurementUnitPoints = 3
Plugin Version: 14.3. Function: One of the units of measurement used by the scanner.
Notes: 1 point = .0352777775 cm or 1/72 inches
13.16.128
ICScannerMeasurementUnitTwips = 4
Plugin Version: 14.3. Function: One of the units of measurement used by the scanner.
Notes: 1 twip = .0001763888 cm or 1/1440 inches
13.16.129
ICScannerPixelDataTypeBW = 0
Plugin Version: 14.3. Function: One of the pixel data types.
Notes: Monochrome 1 bit pixel image.
13.16.130
ICScannerPixelDataTypeCIEXYZ = 8
Plugin Version: 14.3. Function: One of the pixel data types.
Notes: Color image in CIEXYZ color space.
13.16.131
ICScannerPixelDataTypeCMY = 4
Plugin Version: 14.3. Function: One of the pixel data types.
Notes: Color image in CMY color space.
13.16.132
ICScannerPixelDataTypeCMYK = 5
Plugin Version: 14.3. Function: One of the pixel data types.
Notes: Color image in CMYK color space.
13.16. CLASS ICSCANNERFUNCTIONALUNITMBS
13.16.133
ICScannerPixelDataTypeGray = 1
Plugin Version: 14.3. Function: One of the pixel data types.
Notes: 8 bit pixel Gray color space.
13.16.134
ICScannerPixelDataTypePalette = 3
Plugin Version: 14.3. Function: One of the pixel data types.
Notes: Indexed Color image.
13.16.135
ICScannerPixelDataTypeRGB = 2
Plugin Version: 14.3. Function: One of the pixel data types.
Notes: Color image RGB color space.
13.16.136
ICScannerPixelDataTypeYUV = 6
Plugin Version: 14.3. Function: One of the pixel data types.
Notes: Color image in YUV color space.
13.16.137
ICScannerPixelDataTypeYUVK = 7
Plugin Version: 14.3. Function: One of the pixel data types.
Notes: Color image in YUVK color space.
297
298
CHAPTER 13. IMAGE CAPTURE
13.17
class ICScannerFunctionalUnitNegativeTransparencyMBS
13.17.1
class ICScannerFunctionalUnitNegativeTransparencyMBS
Plugin Version: 14.3, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: ICScannerFunctionalUnitNegativeTransparencyMBS is a concrete subclass of ICScannerFunctionalUnitMBS class.
Notes:
ICScannerDeviceMBS creates instances of this class.
This represents the transparency unit on the scanner for scanning negatives.
Subclass of the ICScannerFunctionalUnitMBS class.
This is an abstract class. You can’t create an instance, but you can get one from various plugin functions.
13.17.2
Methods
13.17.3
Constructor
Plugin Version: 14.3, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: The private constructor.
13.18. CLASS ICSCANNERFUNCTIONALUNITPOSITIVETRANSPARENCYMBS
299
13.18
class ICScannerFunctionalUnitPositiveTransparencyMBS
13.18.1
class ICScannerFunctionalUnitPositiveTransparencyMBS
Plugin Version: 14.3, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: ICScannerFunctionalUnitPositiveTransparencyMBS is a concrete subclass of ICScannerFunctionalUnitMBS class.
Notes:
ICScannerDeviceMBS creates instances of this class.
This represents the transparency unit on the scanner for scanning postives.
Subclass of the ICScannerFunctionalUnitMBS class.
This is an abstract class. You can’t create an instance, but you can get one from various plugin functions.
13.18.2
Methods
13.18.3
Constructor
Plugin Version: 14.3, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: The private constructor.
300
CHAPTER 13. IMAGE CAPTURE
13.19
control IKCameraDeviceViewControlMBS
13.19.1
control IKCameraDeviceViewControlMBS
Plugin Version: 14.3, Console & Web: No, Mac: Yes, Win: No, Linux: No. Function: The Xojo control
for a Camera Device View.
Notes: For Xojo with Cocoa target.
13.19.2
Properties
13.19.3
View as IKCameraDeviceViewMBS
Plugin Version: 14.3, Console & Web: No, Mac: Yes, Win: No, Linux: No. Function: The camera device
view used in this control.
Notes: (Read only property)
13.19.4
Events
13.19.5
BoundsChanged
Plugin Version: 17.1, Console & Web: No, Mac: Yes, Win: No, Linux: No. Function: The event called
when the bounds, but not the frame, changed.
13.19.6
DidDownloadFile(CameraFile as ICCameraFileMBS, URL as string,
File as folderItem, data as MemoryBlock, error as NSErrorMBS)
Plugin Version: 14.3, Console & Web: No, Mac: Yes, Win: No, Linux: No. Function: This event is sent
for each file that gets downloaded.
Notes: Based on the IKCameraDeviceViewDisplayMode the downloaded file will be saved on disk using the
’url’, or returned in memory as Memoryblock.
13.19.7
DidEncounterError(Error as NSErrorMBS)
Plugin Version: 14.3, Console & Web: No, Mac: Yes, Win: No, Linux: No. Function: This event is sent
every time the camera device reports an error.
13.19. CONTROL IKCAMERADEVICEVIEWCONTROLMBS
13.19.8
301
EnableMenuItems
Plugin Version: 17.1, Console & Web: No, Mac: Yes, Win: Yes, Linux: Yes. Function: The event where
you can enable menu items.
13.19.9
FrameChanged
Plugin Version: 17.1, Console & Web: No, Mac: Yes, Win: No, Linux: No. Function: The event called
when the frame changed.
13.19.10
GotFocus
Plugin Version: 16.5, Console & Web: No, Mac: Yes, Win: No, Linux: No. Function: The control itself
got focus.
Notes: This only fires if the control itself got focus and not a sub control.
13.19.11
LostFocus
Plugin Version: 16.5, Console & Web: No, Mac: Yes, Win: No, Linux: No. Function: The control lost
focus.
Notes: This only fires if the control itself lost focus and not a sub control.
13.19.12
MenuAction(HitItem as MenuItem) As Boolean
Plugin Version: 17.1, Console & Web: No, Mac: Yes, Win: No, Linux: No. Function: Called when a
menuitem is choosen.
Notes: This allows the control to react on its relevant menu items. Please return true if you handled it or
false to give others a chance.
13.19.13
MouseDown(x as Integer, y as Integer, Modifiers as Integer) As Boolean
Plugin Version: 17.1, Console & Web: No, Mac: Yes, Win: No, Linux: No. Function: The mouse button
was pressed inside the controls region at the location passed in to x, y.
Notes:
The coordinates x and y are local to the control, i.e. they represent the position of the mouse click relative
to the upper-left corner or the Control.
302
CHAPTER 13. IMAGE CAPTURE
Return True if you are going to handle the MouseDown. In such a case:
• The Action event, if any, will not execute and the state of the object will not change.
• You will receive the MouseDrag and MouseUp events.
If you return False, the system handles the MouseDown so the above event handlers do not get called.
13.19.14
MouseDrag(x as Integer, y as Integer)
Plugin Version: 17.1, Console & Web: No, Mac: Yes, Win: No, Linux: No. Function: This event fires
continuously after the mouse button was pressed inside the Control.
Notes:
Mouse location is local to the control passed in to x, y.
As this event is fired continuously (hundreds of time per second), it is your responsibility to determine if the
mouse has really moved.
13.19.15
MouseUp(x as Integer, y as Integer)
Plugin Version: 17.1, Console & Web: No, Mac: Yes, Win: No, Linux: No. Function: The mouse button
was released.
Notes: Use the x and y parameters to determine if the mouse button was released within the control’s
boundaries.
13.19.16
ScaleFactorChanged(NewFactor as Double)
Plugin Version: 17.1, Console & Web: No, Mac: Yes, Win: No, Linux: No. Function: The backing store
scale factor has changed.
Notes: Please invalidate any cached bitmaps or other relevant state.
13.19.17
SelectionDidChange
Plugin Version: 14.3, Console & Web: No, Mac: Yes, Win: No, Linux: No. Function: This event is sent
when the user selection did change.
13.20. CLASS IKCAMERADEVICEVIEWMBS
13.20
class IKCameraDeviceViewMBS
13.20.1
class IKCameraDeviceViewMBS
303
Plugin Version: 14.3, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: Displays content of
a Image Capture supported camera.
Notes: Subclass of the NSViewMBS class.
13.20.2
Methods
13.20.3
Constructor
Plugin Version: 14.3, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: Creates a new box
view with size 100/100 and position 0/0
Example:
dim x as new IKCameraDeviceViewMBS
Notes: On success the handle property is not zero.
See also:
• 13.20.4 Constructor(Handle as Integer)
303
• 13.20.5 Constructor(left as Double, top as Double, width as Double, height as Double)
304
13.20.4
Constructor(Handle as Integer)
Plugin Version: 14.3, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: Creates an object
based on the given NSView handle.
Example:
dim t as new IKCameraDeviceViewMBS(0, 0, 100, 100)
dim v as new IKCameraDeviceViewMBS(t.handle)
MsgBox str(v.Bounds.Width)+” x ”+str(v.Bounds.Height)
Notes: The handle is casted to a IKCameraDeviceView and the plugin retains this handle.
See also:
• 13.20.3 Constructor
303
• 13.20.5 Constructor(left as Double, top as Double, width as Double, height as Double)
304
304
13.20.5
CHAPTER 13. IMAGE CAPTURE
Constructor(left as Double, top as Double, width as Double, height as
Double)
Plugin Version: 14.3, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: Creates a new
control with the given size and position.
Example:
dim left,top,width,height as Integer
// define rectangle
dim x as new IKCameraDeviceViewMBS(left, top, width, height)
Notes: On success the handle property is not zero.
See also:
• 13.20.3 Constructor
303
• 13.20.4 Constructor(Handle as Integer)
303
13.20.6
deleteSelectedItems
Plugin Version: 14.3, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: Delete selected items.
13.20.7
downloadAllItems
Plugin Version: 14.3, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: Download all items.
13.20.8
downloadSelectedItems
Plugin Version: 14.3, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: Download selected
items.
13.20.9
rotateLeft
Plugin Version: 14.3, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: Rotate selected
items left.
13.20. CLASS IKCAMERADEVICEVIEWMBS
13.20.10
305
rotateRight
Plugin Version: 14.3, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: Rotate selected
items right.
13.20.11
selectIndexes(indexes as NSIndexSetMBS, extend as boolean)
Plugin Version: 14.3, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: Setting current user
selection.
13.20.12
Properties
13.20.13
cameraDevice as ICCameraDeviceMBS
Plugin Version: 14.3, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: The camera device.
Notes: (Read and Write property)
13.20.14
canDeleteSelectedItems as Boolean
Plugin Version: 14.3, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: Indicates if the user
selected items can be deleted.
Notes: (Read only property)
13.20.15
canDownloadSelectedItems as Boolean
Plugin Version: 14.3, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: Indicates if the user
selected items can be downloaded.
Notes: (Read only property)
13.20.16
canRotateSelectedItemsLeft as Boolean
Plugin Version: 14.3, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: Indicates if the user
selected items can be rotated left.
Notes: (Read only property)
306
13.20.17
CHAPTER 13. IMAGE CAPTURE
canRotateSelectedItemsRight as Boolean
Plugin Version: 14.3, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: Indicates if the user
selected items can be rotated right.
Notes: (Read only property)
13.20.18
displaysDownloadsDirectoryControl as Boolean
Plugin Version: 14.3, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: Show a downloads
directory control.
Notes: (Read and Write property)
13.20.19
displaysPostProcessApplicationControl as Boolean
Plugin Version: 14.3, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: Show a postprocessing application control.
Notes: (Read and Write property)
13.20.20
downloadAllControlLabel as String
Plugin Version: 14.3, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: Label for the
’Download All’ control - allows for example renaming to ’Import All’.
Notes: (Read and Write property)
13.20.21
downloadsDirectory as String
Plugin Version: 14.3, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: Downloads directory.
Notes:
Download location can be provided as file URL with downloadsDirectory property or as folderitem with
downloadsFolder property.
(Read and Write property)
13.20.22
downloadSelectedControlLabel as String
Plugin Version: 14.3, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: Label for the
’Download Selected’ control.
13.20. CLASS IKCAMERADEVICEVIEWMBS
307
Notes: (Read and Write property)
13.20.23
downloadsFolder as FolderItem
Plugin Version: 14.3, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: Downloads directory.
Notes:
Download location can be provided as file URL with downloadsDirectory property or as folderitem with
downloadsFolder property.
(Read and Write property)
13.20.24
hasDisplayModeIcon as Boolean
Plugin Version: 14.3, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: Support icon view
display mode.
Notes: (Read and Write property)
13.20.25
hasDisplayModeTable as Boolean
Plugin Version: 14.3, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: Support table view
display mode.
Notes: (Read and Write property)
13.20.26
iconSize as Integer
Plugin Version: 14.3, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: in icon mode: size
of the image thumbnails.
Notes: (Read and Write property)
13.20.27
mode as Integer
Plugin Version: 14.3, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: Current display
mode.
Notes:
see IKCameraDeviceViewDisplayMode constants.
(Read and Write property)
308
13.20.28
CHAPTER 13. IMAGE CAPTURE
postProcessApplication as String
Plugin Version: 14.3, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: Postprocessing
application.
Notes:
A file URL to application.
(Read and Write property)
13.20.29
selectedIndexes as NSIndexSetMBS
Plugin Version: 14.3, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: Current user
selection.
Notes: (Read only property)
13.20.30
transferMode as Integer
Plugin Version: 14.3, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: Transfer mode
either file based - or - in memory.
Notes:
See IKCameraDeviceViewTransferMode constants.
(Read and Write property)
13.20.31
Events
13.20.32
DidDownloadFile(CameraFile as ICCameraFileMBS, URL as string,
File as folderItem, data as MemoryBlock, error as NSErrorMBS)
Plugin Version: 14.3, Console & Web: No, Mac: Yes, Win: No, Linux: No. Function: This event is sent
for each file that gets downloaded.
Notes: Based on the IKCameraDeviceViewDisplayMode the downloaded file will be saved on disk using the
’url’, or returned in memory as Memoryblock.
13.20.33
DidEncounterError(Error as NSErrorMBS)
Plugin Version: 14.3, Console & Web: No, Mac: Yes, Win: No, Linux: No. Function: This event is sent
every time the camera device reports an error.
13.20. CLASS IKCAMERADEVICEVIEWMBS
13.20.34
309
SelectionDidChange
Plugin Version: 14.3, Console & Web: No, Mac: Yes, Win: No, Linux: No. Function: This event is sent
when the user selection did change.
13.20.35
Constants
13.20.36
IKCameraDeviceViewDisplayModeIcon = 1
Plugin Version: 14.3. Function: One of the display modes.
Notes: Show Icons
13.20.37
IKCameraDeviceViewDisplayModeTable = 0
Plugin Version: 14.3. Function: One of the display modes.
Notes: Show Table
13.20.38
IKCameraDeviceViewTransferModeFileBased = 0
Plugin Version: 14.3. Function: One of the transfer mode constants.
Notes: File based download.
13.20.39
IKCameraDeviceViewTransferModeMemoryBased = 1
Plugin Version: 14.3. Function: One of the transfer mode constants.
Notes: Memory based download.
310
CHAPTER 13. IMAGE CAPTURE
13.21
control IKDeviceBrowserViewControlMBS
13.21.1
control IKDeviceBrowserViewControlMBS
Plugin Version: 14.3, Console & Web: No, Mac: Yes, Win: No, Linux: No. Function: The Xojo control
for a Device Browser View.
Notes: For Xojo with Cocoa target.
13.21.2
Properties
13.21.3
View as IKDeviceBrowserViewMBS
Plugin Version: 14.3, Console & Web: No, Mac: Yes, Win: No, Linux: No. Function: The device browser
view used in this control.
Notes: (Read only property)
13.21.4
Events
13.21.5
BoundsChanged
Plugin Version: 17.1, Console & Web: No, Mac: Yes, Win: No, Linux: No. Function: The event called
when the bounds, but not the frame, changed.
13.21.6
DidEncounterError(error as NSErrorMBS)
Plugin Version: 14.3, Console & Web: No, Mac: Yes, Win: No, Linux: No. Function: This event is sent
every time the device browser reports an error.
13.21.7
EnableMenuItems
Plugin Version: 17.1, Console & Web: No, Mac: Yes, Win: Yes, Linux: Yes. Function: The event where
you can enable menu items.
13.21. CONTROL IKDEVICEBROWSERVIEWCONTROLMBS
13.21.8
311
FrameChanged
Plugin Version: 17.1, Console & Web: No, Mac: Yes, Win: No, Linux: No. Function: The event called
when the frame changed.
13.21.9
GotFocus
Plugin Version: 16.5, Console & Web: No, Mac: Yes, Win: No, Linux: No. Function: The control itself
got focus.
Notes: This only fires if the control itself got focus and not a sub control.
13.21.10
LostFocus
Plugin Version: 16.5, Console & Web: No, Mac: Yes, Win: No, Linux: No. Function: The control lost
focus.
Notes: This only fires if the control itself lost focus and not a sub control.
13.21.11
MenuAction(HitItem as MenuItem) As Boolean
Plugin Version: 17.1, Console & Web: No, Mac: Yes, Win: No, Linux: No. Function: Called when a
menuitem is choosen.
Notes: This allows the control to react on its relevant menu items. Please return true if you handled it or
false to give others a chance.
13.21.12
MouseDown(x as Integer, y as Integer, Modifiers as Integer) As Boolean
Plugin Version: 17.1, Console & Web: No, Mac: Yes, Win: No, Linux: No. Function: The mouse button
was pressed inside the controls region at the location passed in to x, y.
Notes:
The coordinates x and y are local to the control, i.e. they represent the position of the mouse click relative
to the upper-left corner or the Control.
Return True if you are going to handle the MouseDown. In such a case:
• The Action event, if any, will not execute and the state of the object will not change.
• You will receive the MouseDrag and MouseUp events.
If you return False, the system handles the MouseDown so the above event handlers do not get called.
312
13.21.13
CHAPTER 13. IMAGE CAPTURE
MouseDrag(x as Integer, y as Integer)
Plugin Version: 17.1, Console & Web: No, Mac: Yes, Win: No, Linux: No. Function: This event fires
continuously after the mouse button was pressed inside the Control.
Notes:
Mouse location is local to the control passed in to x, y.
As this event is fired continuously (hundreds of time per second), it is your responsibility to determine if the
mouse has really moved.
13.21.14
MouseUp(x as Integer, y as Integer)
Plugin Version: 17.1, Console & Web: No, Mac: Yes, Win: No, Linux: No. Function: The mouse button
was released.
Notes: Use the x and y parameters to determine if the mouse button was released within the control’s
boundaries.
13.21.15
ScaleFactorChanged(NewFactor as Double)
Plugin Version: 17.1, Console & Web: No, Mac: Yes, Win: No, Linux: No. Function: The backing store
scale factor has changed.
Notes: Please invalidate any cached bitmaps or other relevant state.
13.21.16
SelectionDidChange(device as ICDeviceMBS)
Plugin Version: 14.3, Console & Web: No, Mac: Yes, Win: No, Linux: No. Function: This event is sent
when the user selection did change.
Notes: The device may be a ICCameraDeviceMBS or a ICScannerDeviceMBS.
13.22. CLASS IKDEVICEBROWSERVIEWMBS
13.22
class IKDeviceBrowserViewMBS
13.22.1
class IKDeviceBrowserViewMBS
313
Plugin Version: 14.3, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: Displays Image
Capture cameras and scanners.
Notes: Subclass of the NSViewMBS class.
13.22.2
Methods
13.22.3
Constructor
Plugin Version: 14.3, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: Creates a new box
view with size 100/100 and position 0/0
Example:
dim x as new IKDeviceBrowserViewMBS
Notes: On success the handle property is not zero.
See also:
• 13.22.4 Constructor(Handle as Integer)
313
• 13.22.5 Constructor(left as Double, top as Double, width as Double, height as Double)
314
13.22.4
Constructor(Handle as Integer)
Plugin Version: 14.3, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: Creates an object
based on the given NSView handle.
Example:
dim t as new IKDeviceBrowserViewMBS(0, 0, 100, 100)
dim v as new IKDeviceBrowserViewMBS(t.handle)
MsgBox str(v.Bounds.Width)+” x ”+str(v.Bounds.Height)
Notes: The handle is casted to a IKDeviceBrowserView and the plugin retains this handle.
See also:
• 13.22.3 Constructor
313
• 13.22.5 Constructor(left as Double, top as Double, width as Double, height as Double)
314
314
13.22.5
CHAPTER 13. IMAGE CAPTURE
Constructor(left as Double, top as Double, width as Double, height as
Double)
Plugin Version: 14.3, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: Creates a new
control with the given size and position.
Example:
dim left,top,width,height as Integer
// define rectangle
dim x as new IKDeviceBrowserViewMBS(left, top, width, height)
Notes: On success the handle property is not zero.
See also:
• 13.22.3 Constructor
313
• 13.22.4 Constructor(Handle as Integer)
313
13.22.6
Properties
13.22.7
displaysLocalCameras as Boolean
Plugin Version: 14.3, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: For device filtering
- indicates that the IKDeviceBrowserView should include local cameras.
Notes: (Read and Write property)
13.22.8
displaysLocalScanners as Boolean
Plugin Version: 14.3, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: for device filtering
- indicates that the IKDeviceBrowserView should include local scanners.
Notes: (Read and Write property)
13.22.9
displaysNetworkCameras as Boolean
Plugin Version: 14.3, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: for device filtering
- indicates that the IKDeviceBrowserView should include network/shared cameras.
Notes: (Read and Write property)
13.22. CLASS IKDEVICEBROWSERVIEWMBS
13.22.10
315
displaysNetworkScanners as Boolean
Plugin Version: 14.3, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: for device filtering
- indicates that the IKDeviceBrowserView should include network/shared scanners.
Notes: (Read and Write property)
13.22.11
mode as Integer
Plugin Version: 14.3, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: One of the supported
display modes (table, outline, or icon mode).
Notes: (Read and Write property)
13.22.12
selectedDevice as ICDeviceMBS
Plugin Version: 14.3, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: User selected device
(ICCameraDevice or ICScannerDevice).
Notes: (Read only property)
13.22.13
Events
13.22.14
DidEncounterError(error as NSErrorMBS)
Plugin Version: 14.3, Console & Web: No, Mac: Yes, Win: No, Linux: No. Function: This event is sent
every time the device browser reports an error.
13.22.15
SelectionDidChange(device as ICDeviceMBS)
Plugin Version: 14.3, Console & Web: No, Mac: Yes, Win: No, Linux: No. Function: This event is sent
when the user selection did change.
Notes: The device may be a ICCameraDeviceMBS or a ICScannerDeviceMBS.
13.22.16
Constants
13.22.17
IKDeviceBrowserViewDisplayModeIcon = 2
Plugin Version: 14.3. Function: One of the display modes.
Notes: Icon
316
13.22.18
CHAPTER 13. IMAGE CAPTURE
IKDeviceBrowserViewDisplayModeOutline = 1
Plugin Version: 14.3. Function: One of the display modes.
Notes: Outline
13.22.19
IKDeviceBrowserViewDisplayModeTable = 0
Plugin Version: 14.3. Function: One of the display modes.
Notes: Table
13.23. CONTROL IKSCANNERDEVICEVIEWCONTROLMBS
13.23
control IKScannerDeviceViewControlMBS
13.23.1
control IKScannerDeviceViewControlMBS
317
Plugin Version: 14.3, Console & Web: No, Mac: Yes, Win: No, Linux: No. Function: The Xojo control
for a Scanner Device View.
Notes: For Xojo with Cocoa target.
13.23.2
Properties
13.23.3
View as IKScannerDeviceViewMBS
Plugin Version: 14.3, Console & Web: No, Mac: Yes, Win: No, Linux: No. Function: The scanner view
used in this control.
Notes: (Read only property)
13.23.4
Events
13.23.5
BoundsChanged
Plugin Version: 17.1, Console & Web: No, Mac: Yes, Win: No, Linux: No. Function: The event called
when the bounds, but not the frame, changed.
13.23.6
DidEncounterError(error as NSErrorMBS)
Plugin Version: 14.3, Console & Web: No, Mac: Yes, Win: No, Linux: No. Function: This event is sent
every time the scanner device reports an error.
13.23.7
DidScanToBandData(data as ICScannerBandDataMBS, scanInfo as Dictionary, error as NSErrorMBS)
Plugin Version: 14.3, Console & Web: No, Mac: Yes, Win: No, Linux: No. Function: For memory a based
transfer this event is sent for every time an image band of data was scanned.
Notes: The ’data’ parameter describes the scanned image data. Note that rotation/cropping/image adjustments are not applied yet. The ’scanInfo’ parameter contains additional information (rotation angle, ...)
that should be applied once the scan is completed.
318
13.23.8
CHAPTER 13. IMAGE CAPTURE
DidScanToURL(url as String, file as FolderItem, fileData as MemoryBlock, error as NSErrorMBS)
Plugin Version: 14.3, Console & Web: No, Mac: Yes, Win: No, Linux: No. Function: For file based
transfer this event is sent for each image that gets scanned.
Notes: Based on the IKScannerDeviceViewTransferMode the downloaded file will be saved on disk using
the ’url’, or returned in memory as Memoryblock.
13.23.9
EnableMenuItems
Plugin Version: 17.1, Console & Web: No, Mac: Yes, Win: No, Linux: No. Function: The event where
you can enable menu items.
13.23.10
FrameChanged
Plugin Version: 17.1, Console & Web: No, Mac: Yes, Win: No, Linux: No. Function: The event called
when the frame changed.
13.23.11
GotFocus
Plugin Version: 16.5, Console & Web: No, Mac: Yes, Win: No, Linux: No. Function: The control itself
got focus.
Notes: This only fires if the control itself got focus and not a sub control.
13.23.12
LostFocus
Plugin Version: 16.5, Console & Web: No, Mac: Yes, Win: No, Linux: No. Function: The control lost
focus.
Notes: This only fires if the control itself lost focus and not a sub control.
13.23.13
MenuAction(HitItem as MenuItem) As Boolean
Plugin Version: 17.1, Console & Web: No, Mac: Yes, Win: No, Linux: No. Function: Called when a
menuitem is choosen.
Notes: This allows the control to react on its relevant menu items. Please return true if you handled it or
false to give others a chance.
13.23. CONTROL IKSCANNERDEVICEVIEWCONTROLMBS
13.23.14
319
MouseDown(x as Integer, y as Integer, Modifiers as Integer) As Boolean
Plugin Version: 17.1, Console & Web: No, Mac: Yes, Win: No, Linux: No. Function: The mouse button
was pressed inside the controls region at the location passed in to x, y.
Notes:
The coordinates x and y are local to the control, i.e. they represent the position of the mouse click relative
to the upper-left corner or the Control.
Return True if you are going to handle the MouseDown. In such a case:
• The Action event, if any, will not execute and the state of the object will not change.
• You will receive the MouseDrag and MouseUp events.
If you return False, the system handles the MouseDown so the above event handlers do not get called.
13.23.15
MouseDrag(x as Integer, y as Integer)
Plugin Version: 17.1, Console & Web: No, Mac: Yes, Win: No, Linux: No. Function: This event fires
continuously after the mouse button was pressed inside the Control.
Notes:
Mouse location is local to the control passed in to x, y.
As this event is fired continuously (hundreds of time per second), it is your responsibility to determine if the
mouse has really moved.
13.23.16
MouseUp(x as Integer, y as Integer)
Plugin Version: 17.1, Console & Web: No, Mac: Yes, Win: No, Linux: No. Function: The mouse button
was released.
Notes: Use the x and y parameters to determine if the mouse button was released within the control’s
boundaries.
13.23.17
ScaleFactorChanged(NewFactor as Double)
Plugin Version: 17.1, Console & Web: No, Mac: Yes, Win: No, Linux: No. Function: The backing store
scale factor has changed.
Notes: Please invalidate any cached bitmaps or other relevant state.
320
CHAPTER 13. IMAGE CAPTURE
13.24
class IKScannerDeviceViewMBS
13.24.1
class IKScannerDeviceViewMBS
Plugin Version: 14.3, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: IKScannerDeviceView displays a UI to work with Image Capture supported scanners.
Notes: Subclass of the NSViewMBS class.
13.24.2
Methods
13.24.3
Constructor
Plugin Version: 14.3, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: Creates a new box
view with size 100/100 and position 0/0
Example:
dim x as new IKScannerDeviceViewMBS
Notes: On success the handle property is not zero.
See also:
• 13.24.4 Constructor(Handle as Integer)
320
• 13.24.5 Constructor(left as Double, top as Double, width as Double, height as Double)
321
13.24.4
Constructor(Handle as Integer)
Plugin Version: 14.3, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: Creates an object
based on the given NSView handle.
Example:
dim t as new IKScannerDeviceViewMBS(0, 0, 100, 100)
dim v as new IKScannerDeviceViewMBS(t.handle)
MsgBox str(v.Bounds.Width)+” x ”+str(v.Bounds.Height)
Notes: The handle is casted to a IKScannerDeviceView and the plugin retains this handle.
See also:
• 13.24.3 Constructor
320
• 13.24.5 Constructor(left as Double, top as Double, width as Double, height as Double)
321
13.24. CLASS IKSCANNERDEVICEVIEWMBS
13.24.5
321
Constructor(left as Double, top as Double, width as Double, height as
Double)
Plugin Version: 14.3, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: Creates a new
control with the given size and position.
Example:
dim left,top,width,height as Integer
// define rectangle
dim x as new IKScannerDeviceViewMBS(left, top, width, height)
Notes: On success the handle property is not zero.
See also:
• 13.24.3 Constructor
320
• 13.24.4 Constructor(Handle as Integer)
320
13.24.6
Properties
13.24.7
displaysDownloadsDirectoryControl as Boolean
Plugin Version: 14.3, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: Show a downloads
directory control.
Notes: (Read and Write property)
13.24.8
displaysPostProcessApplicationControl as Boolean
Plugin Version: 14.3, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: Show a postprocessing application control.
Notes: (Read and Write property)
13.24.9
documentName as String
Plugin Version: 14.3, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: Document name.
Notes: (Read and Write property)
322
13.24.10
CHAPTER 13. IMAGE CAPTURE
downloadsDirectory as String
Plugin Version: 14.3, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: Downloads directory.
Notes:
Download location can be provided as file URL with downloadsDirectory property or as folderitem with
downloadsFolder property.
(Read and Write property)
13.24.11
downloadsFolder as FolderItem
Plugin Version: 14.3, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: Downloads directory.
Notes:
Download location can be provided as file URL with downloadsDirectory property or as folderitem with
downloadsFolder property.
(Read and Write property)
13.24.12
hasDisplayModeAdvanced as Boolean
Plugin Version: 14.3, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: Support advanced
scanning UI.
Notes: (Read and Write property)
13.24.13
hasDisplayModeSimple as Boolean
Plugin Version: 14.3, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: Support a simple
scanning UI.
Notes: (Read and Write property)
13.24.14
mode as Integer
Plugin Version: 14.3, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: Current display
mode.
Notes:
See IKScannerDeviceViewDisplayMode constants.
(Read and Write property)
13.24. CLASS IKSCANNERDEVICEVIEWMBS
13.24.15
323
overviewControlLabel as String
Plugin Version: 14.3, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: Label for the
’Overview’ control.
Notes: (Read and Write property)
13.24.16
postProcessApplication as String
Plugin Version: 14.3, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: Postprocessing
application.
Notes: (Read and Write property)
13.24.17
scanControlLabel as String
Plugin Version: 14.3, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: label for the ’Scan’
control.
Notes: (Read and Write property)
13.24.18
scannerDevice as ICScannerDeviceMBS
Plugin Version: 14.3, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: The scanner device.
Notes: (Read and Write property)
13.24.19
transferMode as Integer
Plugin Version: 14.3, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: transfer mode either
file based - or - in memory.
Notes:
See IKScannerDeviceViewTransferMode constants.
(Read and Write property)
13.24.20
Events
13.24.21
DidEncounterError(error as NSErrorMBS)
Plugin Version: 14.3, Console & Web: No, Mac: Yes, Win: No, Linux: No. Function: This event is sent
every time the scanner device reports an error.
324
13.24.22
CHAPTER 13. IMAGE CAPTURE
DidScanToBandData(data as ICScannerBandDataMBS, scanInfo as
Dictionary, error as NSErrorMBS)
Plugin Version: 14.3, Console & Web: No, Mac: Yes, Win: No, Linux: No. Function: For memory a based
transfer this event is sent for every time an image band of data was scanned.
Notes: The ’data’ parameter describes the scanned image data. Note that rotation/cropping/image adjustments are not applied yet. The ’scanInfo’ parameter contains additional information (rotation angle, ...)
that should be applied once the scan is completed.
13.24.23
DidScanToURL(url as String, file as FolderItem, fileData as MemoryBlock, error as NSErrorMBS)
Plugin Version: 14.3, Console & Web: No, Mac: Yes, Win: No, Linux: No. Function: For file based
transfer this event is sent for each image that gets scanned.
Notes: Based on the IKScannerDeviceViewTransferMode the downloaded file will be saved on disk using
the ’url’, or returned in memory as Memoryblock.
13.24.24
Constants
13.24.25
IKScannerDeviceViewDisplayModeAdvanced = 1
Plugin Version: 14.3. Function: One of the display mode constants.
Notes: Advanced
13.24.26
IKScannerDeviceViewDisplayModeSimple = 0
Plugin Version: 14.3. Function: One of the display mode constants.
Notes: Simple
13.24.27
IKScannerDeviceViewTransferModeFileBased = 0
Plugin Version: 14.3. Function: One of the transport modes.
Notes: File based scan.
13.24. CLASS IKSCANNERDEVICEVIEWMBS
13.24.28
IKScannerDeviceViewTransferModeMemoryBased = 1
Plugin Version: 14.3. Function: One of the transport modes.
Notes: Memory based scan.
325
326
CHAPTER 13. IMAGE CAPTURE
13.25
class ImageCaptureEventsMBS
13.25.1
class ImageCaptureEventsMBS
Plugin Version: 14.3, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: Central class for
Image Capture events.
Notes:
Whenever you have an ICA object, the plugin will register a delegate for it and dispatch all events here.
For some view classes, events are in addition dispatched to the controls.
13.25.2
Properties
13.25.3
Handle as Integer
Plugin Version: 14.3, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: The internal object
reference.
Notes: (Read and Write property)
13.25.4
Events
13.25.5
cameraDeviceDidAddItem(camera as ICCameraDeviceMBS, item as
ICCameraItemMBS)
Plugin Version: 14.3, Console & Web: No, Mac: Yes, Win: No, Linux: No. Function: This event is sent
when an object is added to the device.
Notes: The object may be an instance of ICCameraFolder or ICCameraFile class.
13.25.6
cameraDeviceDidAddItems(camera as ICCameraDeviceMBS, items()
as ICCameraItemMBS)
Plugin Version: 14.3, Console & Web: No, Mac: Yes, Win: No, Linux: No. Function: This event is sent
when an object or objects are added to the device.
Notes:
Instead of receive one event per object, an array of objects is sent.
The objects may be instances of ICCameraFolder or ICCameraFile class.
13.25. CLASS IMAGECAPTUREEVENTSMBS
13.25.7
327
cameraDeviceDidBecomeReadyWithCompleteContentCatalog(camera as
ICCameraDeviceMBS)
Plugin Version: 14.3, Console & Web: No, Mac: Yes, Win: No, Linux: No. Function: This event is sent
when the camera device is done enumerating its content and is ready to receive requests.
Notes: A session must be opened on the device in order to enumerate its content and make it ready to
receive requests.
13.25.8
cameraDeviceDidChangeCapability(camera as ICCameraDeviceMBS)
Plugin Version: 14.3, Console & Web: No, Mac: Yes, Win: No, Linux: No. Function: This event is sent
when the capability of a device changes.
Notes: This usually happens when the device module takes control or yields control of the device.
13.25.9
cameraDeviceDidCompleteDeleteFilesWithError(camera as ICCameraDeviceMBS, error as NSErrorMBS)
Plugin Version: 14.3, Console & Web: No, Mac: Yes, Win: No, Linux: No. Function: Files have been
deleted.
Notes: This event is sent after the camera device completes a delete operation initiated by sending a requestDeleteFiles event to that device.
13.25.10
cameraDeviceDidDownloadFile(file as ICCameraFileMBS, error as NSErrorMBS, options as Dictionary, device as ICCameraDeviceMBS)
Plugin Version: 14.3, Console & Web: No, Mac: Yes, Win: No, Linux: No. Function: Download of file
finished.
13.25.11
cameraDeviceDidReadData(data as Memoryblock, file as ICCameraFileMBS, error as NSErrorMBS, device as ICCameraDeviceMBS)
Plugin Version: 14.3, Console & Web: No, Mac: Yes, Win: No, Linux: No. Function: Reading file data
finished.
328
13.25.12
CHAPTER 13. IMAGE CAPTURE
cameraDeviceDidReceiveDownloadProgressForFile(file as ICCameraFileMBS,
downloadedBytes as UInt64, maxBytes as UInt64)
Plugin Version: 14.3, Console & Web: No, Mac: Yes, Win: No, Linux: No. Function: This event is sent to
the delegate to provide status of the download operation.
13.25.13
cameraDeviceDidReceiveMetadataForItem(camera as ICCameraDeviceMBS,
item as ICCameraItemMBS)
Plugin Version: 14.3, Console & Web: No, Mac: Yes, Win: No, Linux: No. Function: This event is sent
when the metadata requested for an item on a device is available.
13.25.14
cameraDeviceDidReceivePTPEvent(camera as ICCameraDeviceMBS,
eventData as MemoryBlock)
Plugin Version: 14.3, Console & Web: No, Mac: Yes, Win: No, Linux: No. Function: This event is sent to
the delegate to convey a PTP event.
13.25.15
cameraDeviceDidReceiveThumbnailForItem(camera as ICCameraDeviceMBS, item as ICCameraItemMBS)
Plugin Version: 14.3, Console & Web: No, Mac: Yes, Win: No, Linux: No. Function: This event is sent
when the thumbnail requested for an item on a device is available.
13.25.16
cameraDeviceDidRemoveItem(camera as ICCameraDeviceMBS, item
as ICCameraItemMBS)
Plugin Version: 14.3, Console & Web: No, Mac: Yes, Win: No, Linux: No. Function: This event is sent
when an object is removed from the device.
Notes: The object may be an instance of ICCameraFolder or ICCameraFile class.
13.25.17
cameraDeviceDidRemoveItems(camera as ICCameraDeviceMBS, items()
as ICCameraItemMBS)
Plugin Version: 14.3, Console & Web: No, Mac: Yes, Win: No, Linux: No. Function: This event is sent
when an object or objects are removed from the device.
13.25. CLASS IMAGECAPTUREEVENTSMBS
329
Notes: The objects may be instances of ICCameraFolder or ICCameraFile class. This method supercedes
cameraDeviceDidRemoveItem method described above.
13.25.18
cameraDeviceDidRenameItems(camera as ICCameraDeviceMBS, items()
as ICCameraItemMBS)
Plugin Version: 14.3, Console & Web: No, Mac: Yes, Win: No, Linux: No. Function: This event is sent
when an object or objects are renamed on the device.
Notes: The objects may be instances of ICCameraFolder or ICCameraFile class.
13.25.19
cameraDeviceDidSendPTPCommand(command as Memoryblock, data
as Memoryblock, response as MemoryBlock, error as NSErrorMBS,
device as ICCameraDeviceMBS)
Plugin Version: 14.3, Console & Web: No, Mac: Yes, Win: No, Linux: No. Function: Called when a
requestSendPTPCommand event got a response or error.
13.25.20
cameraDeviceDidUploadFile(fileURL as string, file as FolderItem, error as NSErrorMBS, device as ICCameraDeviceMBS)
Plugin Version: 14.3, Console & Web: No, Mac: Yes, Win: No, Linux: No. Function: A file upload was
completed.
13.25.21
cameraDeviceViewDidDownloadFile(cameraDeviceView as IKCameraDeviceViewMBS, CameraFile as ICCameraFileMBS, URL as string,
File as folderItem, data as MemoryBlock, error as NSErrorMBS)
Plugin Version: 14.3, Console & Web: No, Mac: Yes, Win: No, Linux: No. Function: This event is sent
for each file that gets downloaded.
Notes: Based on the IKCameraDeviceViewDisplayMode the downloaded file will be saved on disk using the
’url’, or returned in memory as Memoryblock.
13.25.22
cameraDeviceViewDidEncounterError(cameraDeviceView as IKCameraDeviceViewMBS, error as NSErrorMBS)
Plugin Version: 14.3, Console & Web: No, Mac: Yes, Win: No, Linux: No. Function: This event is sent
every time the camera device reports an error.
330
13.25.23
CHAPTER 13. IMAGE CAPTURE
cameraDeviceViewSelectionDidChange(cameraDeviceView as IKCameraDeviceViewMBS)
Plugin Version: 14.3, Console & Web: No, Mac: Yes, Win: No, Linux: No. Function: This event is sent
when the user selection did change.
13.25.24
deviceBrowserDeviceDidChangeName(browser as ICDeviceBrowserMBS,
device as ICDeviceMBS)
Plugin Version: 14.3, Console & Web: No, Mac: Yes, Win: No, Linux: No. Function: This event is sent if
the name of a device changes.
Notes: This happens if the device module overrides the default name of the device reported by the device’s
transport layer, or if the name of the filesystem volume mounted by the device is changed by the user.
13.25.25
deviceBrowserDeviceDidChangeSharingState(browser as ICDeviceBrowserMBS,
device as ICDeviceMBS)
Plugin Version: 14.3, Console & Web: No, Mac: Yes, Win: No, Linux: No. Function: This event is sent
when the sharing state of a device has changes.
Notes: Any Image Capture client application can choose to share the device over the network using the
sharing or webSharing facility in Image Capture.
13.25.26
deviceBrowserDidAddDevice(browser as ICDeviceBrowserMBS, device as ICDeviceMBS, moreComing as boolean)
Plugin Version: 14.3, Console & Web: No, Mac: Yes, Win: No, Linux: No. Function: This event is sent to
the delegate to inform that a device has been added.
Notes: If several devices are found during the initial search, then this event is sent once for each device
with the value of ’moreComing’ set to true in each event except the last one.
13.25.27
deviceBrowserDidEnumerateLocalDevices(browser as ICDeviceBrowserMBS)
Plugin Version: 14.3, Console & Web: No, Mac: Yes, Win: No, Linux: No. Function: This event is sent
after the device browser completes sending deviceBrowserDidAddDevice event for all local devices.
Notes: Detecting locally connected devices (USB and FireWire devices) is faster than detecting devices
connected using a network protocol. An Image Capture client application may use this event to update its
13.25. CLASS IMAGECAPTUREEVENTSMBS
331
user interface to let the user know that it has completed looking for locally connected devices and then start
looking for network devices.
13.25.28
deviceBrowserDidRemoveDevice(browser as ICDeviceBrowserMBS, device as ICDeviceMBS, moreGoing as boolean)
Plugin Version: 14.3, Console & Web: No, Mac: Yes, Win: No, Linux: No. Function: This event is sent to
the delegate to inform that a device has been removed.
Notes: If several devices are removed at the same time, then this event is sent once for each device with
the value of ’moreGoing’ set to true in each event except the last one.
13.25.29
deviceBrowserRequestsSelectDevice(browser as ICDeviceBrowserMBS,
device as ICDeviceMBS)
Plugin Version: 14.3, Console & Web: No, Mac: Yes, Win: No, Linux: No. Function: This event is sent
when an event that occurred on the device may be of interest to the client application.
Notes: In Mac OS X 10.6, this event is sent when a button is pressed on a device and the current application
is the target for that button press. In the case of the button-press event, if a session is open on the device,
this event will not be sent, instead the deviceDidReceiveButtonPress event is sent.
13.25.30
deviceBrowserViewDidEncounterError(deviceBrowserView as IKDeviceBrowserViewMBS, error as NSErrorMBS)
Plugin Version: 14.3, Console & Web: No, Mac: Yes, Win: No, Linux: No. Function: This event is sent
every time the device browser reports an error.
13.25.31
deviceBrowserViewSelectionDidChange(deviceBrowserView as IKDeviceBrowserViewMBS, device as ICDeviceMBS)
Plugin Version: 14.3, Console & Web: No, Mac: Yes, Win: No, Linux: No. Function: This event is sent
when the user selection did change.
Notes: The device may be a ICCameraDeviceMBS or a ICScannerDeviceMBS.
13.25.32
deviceDidBecomeReady(device as ICDeviceMBS)
Plugin Version: 14.3, Console & Web: No, Mac: Yes, Win: No, Linux: No. Function: This event is sent
when the device is ready to receive requests.
332
CHAPTER 13. IMAGE CAPTURE
Notes: A camera device is ready, when it is ready to receive requests. A scanner device is ready when its
functional units are found and the default functional unit is selected for use and is ready to receive requests.
The device will become ready to receive requests only after a session is opened.
13.25.33
deviceDidChangeName(device as ICDeviceMBS)
Plugin Version: 14.3, Console & Web: No, Mac: Yes, Win: No, Linux: No. Function: This event is sent if
the name of a device changes.
Notes: This happens if the device module overrides the default name of the device reported by the device’s
transport layer, or if the name of the filesystem volume mounted by the device is changed by the user.
13.25.34
deviceDidChangeSharingState(device as ICDeviceMBS)
Plugin Version: 14.3, Console & Web: No, Mac: Yes, Win: No, Linux: No. Function: This event is sent
when the sharing state of a device has changes.
Notes: Any Image Capture client application can choose to share the device over the network using the
sharing or webSharing facility in Image Capture.
13.25.35
deviceDidCloseSessionWithError(device as ICDeviceMBS, error as NSErrorMBS)
Plugin Version: 14.3, Console & Web: No, Mac: Yes, Win: No, Linux: No. Function: This event is sent
when a session is closed on a device.
Notes: This event completes the process initiated by the message ”requestCloseSession” sent to the device
object. This event is also sent if the device module in control of the device ceases to control the device.
13.25.36
deviceDidEncounterError(device as ICDeviceMBS, error as NSErrorMBS)
Plugin Version: 14.3, Console & Web: No, Mac: Yes, Win: No, Linux: No. Function: This event is sent to
the device delegate when a camera or scanner device encounters an error.
13.25.37
deviceDidOpenSessionWithError(device as ICDeviceMBS, error as NSErrorMBS)
Plugin Version: 14.3, Console & Web: No, Mac: Yes, Win: No, Linux: No. Function: This event is sent
when a session is opened on a device.
13.25. CLASS IMAGECAPTUREEVENTSMBS
333
Notes: This event completes the process initiated by the requestOpenSession sent to the device object.
13.25.38
deviceDidReceiveButtonPress(device as ICDeviceMBS, buttonType
as String)
Plugin Version: 14.3, Console & Web: No, Mac: Yes, Win: No, Linux: No. Function: This event is sent to
the device delegate if a button is pressed on the device.
Notes: This event is sent only if a session is open on the device. The value of ’buttonType’ argument is
one of the ICButtonType* values defined above.
13.25.39
deviceDidReceiveCustomNotification(device as ICDeviceMBS, notification as Dictionary, data as Memoryblock)
Plugin Version: 14.3, Console & Web: No, Mac: Yes, Win: No, Linux: No. Function: This event is sent to
the device delegate the device sends a custom notification ’notification’ with an arbitrary byte buffer ’data’.
Notes: This event is sent only if a session is open on the device.
13.25.40
deviceDidReceiveStatusInformation(device as ICDeviceMBS, status
as Dictionary)
Plugin Version: 14.3, Console & Web: No, Mac: Yes, Win: No, Linux: No. Function: This event is sent
when status information is received from a camera or a scanner.
Notes:
In Mac OS X 10.6 this event is not called for camera devices. This may change in the future releases of Mac
OS X.
The ’status’ dictionary contains two keys, ICStatusNotificationKey and ICLocalizedStatusNotificationKey,
which are defined above. If type of ’device’ is ICDeviceTypeScanner, the value of ICStatusNotificationKey
will be one of the values defined in ICScannerDevice.h (e.g., ICScannerStatusWarmingUp, ICScannerStatusWarmUpDone, or ICScannerStatusRequestsOverviewScan); the value of ICLocalizedStatusNotificationKey will be a localized status information string suitable for displaying to the user.
13.25.41
deviceDidRemove(device as ICDeviceMBS)
Plugin Version: 14.3, Console & Web: No, Mac: Yes, Win: No, Linux: No. Function: This event is sent to
the delegate to inform that a device has been removed.
334
13.25.42
CHAPTER 13. IMAGE CAPTURE
deviceDidSendMessage(messageCode as UInt32, data as Memoryblock,
error as NSErrorMBS, device as ICDeviceMBS)
Plugin Version: 14.3, Console & Web: No, Mac: Yes, Win: No, Linux: No. Function: The call to requestSendMessage was successful.
13.25.43
scannerDeviceDidBecomeAvailable(scanner as ICScannerDeviceMBS)
Plugin Version: 14.3, Console & Web: No, Mac: Yes, Win: No, Linux: No. Function: This event is sent
when another client closes an open session on the scanner.
Notes: Scanners require exclusive access, only one client can open a session on a scanner. The scanner is
available if it does not have a session opened by another client. Attempting to open a session on a scanner
that already has an open session for another client will result in an error. A client that wants to open a
session on a scanner as soon as it is available should implement this method and send ”requestOpenSession”
message to scanner object from that method.
13.25.44
scannerDeviceDidCompleteOverviewScanWithError(scanner as ICScannerDeviceMBS, error as NSErrorMBS)
Plugin Version: 14.3, Console & Web: No, Mac: Yes, Win: No, Linux: No. Function: This event is sent
after the scanner device completes an overview scan.
13.25.45
scannerDeviceDidCompleteScanWithError(scanner as ICScannerDeviceMBS, error as NSErrorMBS)
Plugin Version: 14.3, Console & Web: No, Mac: Yes, Win: No, Linux: No. Function: This event is sent
after the scanner device completes a scan.
13.25.46
scannerDeviceDidScanToBandData(scanner as ICScannerDeviceMBS,
Data as ICScannerBandDataMBS)
Plugin Version: 14.3, Console & Web: No, Mac: Yes, Win: No, Linux: No. Function: This event is sent
when the scanner device receives the requested scan progress notification and a band of data is sent for each
notification received.
Notes: In memory transfer mode, this will send a band of size that has been selected by the client via the
maxMemoryBandSize property.
13.25. CLASS IMAGECAPTUREEVENTSMBS
13.25.47
335
scannerDeviceDidScanToURL(scanner as ICScannerDeviceMBS, URL
as string, file as folderitem, data as MemoryBlock)
Plugin Version: 14.3, Console & Web: No, Mac: Yes, Win: No, Linux: No. Function: This event is sent
when the scanner device receives the requested scan.
Notes:
If selectedFunctionalUnit is a document feeder, then this event will be sent once for each scanned page.
This event is sent when the scanner device receives the requested scan. If selectedFunctionalUnit is a document feeder, then this event will be sent once for each scanned page.
13.25.48
scannerDeviceDidSelectFunctionalUnit(scanner as ICScannerDeviceMBS,
functionalUnit as Variant, Error as NSErrorMBS)
Plugin Version: 14.3, Console & Web: No, Mac: Yes, Win: No, Linux: No. Function: This event is sent
when a functional unit is selected on the scanner device.
Notes: A functional unit is selected immediately after the scanner device is instantiated and in response to
requestSelectFunctionalUnit method.
13.25.49
scannerDeviceViewDidEncounterError(scannerDeviceView as IKScannerDeviceViewMBS, error as NSErrorMBS)
Plugin Version: 14.3, Console & Web: No, Mac: Yes, Win: No, Linux: No. Function: This event is sent
every time the scanner device reports an error.
13.25.50
scannerDeviceViewDidScanToBandData(scannerDeviceView as IKScannerDeviceViewMBS, data as ICScannerBandDataMBS, scanInfo as
Dictionary, error as NSErrorMBS)
Plugin Version: 14.3, Console & Web: No, Mac: Yes, Win: No, Linux: No. Function: For memory a based
transfer this event is sent for every time an image band of data was scanned.
Notes: The ’data’ parameter describes the scanned image data. Note that rotation/cropping/image adjustments are not applied yet. The ’scanInfo’ parameter contains additional information (rotation angle, ...)
that should be applied once the scan is completed.
336
13.25.51
CHAPTER 13. IMAGE CAPTURE
scannerDeviceViewDidScanToURL(scannerDeviceView as IKScannerDeviceViewMBS, url as String, file as FolderItem, fileData as MemoryBlock, error as NSErrorMBS)
Plugin Version: 14.3, Console & Web: No, Mac: Yes, Win: No, Linux: No. Function: For file based
transfer this event is sent for each image that gets scanned.
Notes: Based on the IKScannerDeviceViewTransferMode the downloaded file will be saved on disk using
the ’url’, or returned in memory as Memoryblock.
13.25.52
Constants
13.25.53
ICReturnCommunicationTimedOut = -9923
Plugin Version: 14.3. Function: One of the error constants.
Notes: Communication between different components of Image Capture timed out.
13.25.54
ICReturnDeleteFilesCanceled = -9942
Plugin Version: 14.3. Function: One of the error constants.
Notes: A request to delete files was canceled.
13.25.55
ICReturnDeleteFilesFailed = -9941
Plugin Version: 14.3. Function: One of the error constants.
Notes: A request to delete files failed.
13.25.56
ICReturnDeviceFailedToCloseSession = -9928
Plugin Version: 14.3. Function: One of the error constants.
Notes: Failed to close a session on a specified device.
13.25.57
ICReturnDeviceFailedToOpenSession = -9927
Plugin Version: 14.3. Function: One of the error constants.
Notes: Failed to open a session on a specified device.
13.25. CLASS IMAGECAPTUREEVENTSMBS
13.25.58
ICReturnDeviceFailedToTakePicture = -9944
Plugin Version: 14.3. Function: One of the error constants.
Notes: Failed to take a tethered-capture picture on a camera device.
13.25.59
ICReturnDeviceIsPasscodeLocked = -9943
Plugin Version: 14.3. Function: One of the error constants.
Notes: The device is locked with a passcode. Its contents cannot be seen unless it is unlocked.
13.25.60
ICReturnDeviceSoftwareInstallationCanceled = -9948
Plugin Version: 14.3. Function: One of the error constants.
Notes: Software installation for the device has been canceled.
13.25.61
ICReturnDeviceSoftwareInstallationCompleted = -9947
Plugin Version: 14.3. Function: One of the error constants.
Notes: Software installation for the device has completed successfully.
13.25.62
ICReturnDeviceSoftwareInstallationFailed = -9949
Plugin Version: 14.3. Function: One of the error constants.
Notes: Software installation for the device failed.
13.25.63
ICReturnDeviceSoftwareIsBeingInstalled = -9946
Plugin Version: 14.3. Function: One of the error constants.
Notes: Failed to open session because software to communicate with the device is being installed.
13.25.64
ICReturnDeviceSoftwareNotAvailable = -9950
Plugin Version: 14.3. Function: One of the error constants.
Notes: Software for the device is not available from Apple.
337
338
13.25.65
CHAPTER 13. IMAGE CAPTURE
ICReturnDeviceSoftwareNotInstalled = -9945
Plugin Version: 14.3. Function: One of the error constants.
Notes: Failed to open session because software to communicate with the device is not installed.
13.25.66
ICReturnDownloadCanceled = -9937
Plugin Version: 14.3. Function: One of the error constants.
Notes: A download operation was canceled.
13.25.67
ICReturnDownloadFailed = -9934
Plugin Version: 14.3. Function: One of the error constants.
Notes: A non-specific error occurred while downloading a file.
13.25.68
ICReturnFailedToCompletePassThroughCommand = -9936
Plugin Version: 14.3. Function: One of the error constants.
Notes: Failed to complete a pass-through (e.g., PTP pass-through) command.
13.25.69
ICReturnFailedToCompleteSendMessageRequest = -9940
Plugin Version: 14.3. Function: One of the error constants.
Notes: A request to send a event to a device failed.
13.25.70
ICReturnFailedToDisabeTethering = -9939
Plugin Version: 14.3. Function: One of the error constants.
Notes: Failed to disable tethered-capture on a camera device.
13.25.71
ICReturnFailedToEnabeTethering = -9938
Plugin Version: 14.3. Function: One of the error constants.
Notes: Failed to enable tethered-capture on a camera device.
13.25. CLASS IMAGECAPTUREEVENTSMBS
13.25.72
ICReturnInvalidParam = -9922
Plugin Version: 14.3. Function: One of the error constants.
Notes: An invalid parameter was found.
13.25.73
ICReturnReceivedUnsolicitedScannerErrorInfo = -9933
Plugin Version: 14.3. Function: One of the error constants.
Notes: An unsolicited error information was received from a scanner.
13.25.74
ICReturnReceivedUnsolicitedScannerStatusInfo = -9932
Plugin Version: 14.3. Function: One of the error constants.
Notes: An unsolicited status information was received from a scanner.
13.25.75
ICReturnScannerFailedToCompleteOverviewScan = -9930
Plugin Version: 14.3. Function: One of the error constants.
Notes: Overview scan operation failed to complete on the specified scanner.
13.25.76
ICReturnScannerFailedToCompleteScan = -9931
Plugin Version: 14.3. Function: One of the error constants.
Notes: Scan operation failed to complete on the specified scanner.
13.25.77
ICReturnScannerFailedToSelectFunctionalUnit = -9929
Plugin Version: 14.3. Function: One of the error constants.
Notes: Failed to select a functional unit on the specified scanner.
13.25.78
ICReturnScannerInUseByLocalUser = -9925
Plugin Version: 14.3. Function: One of the error constants.
Notes: Scanner is being used by a remote user.
339
340
13.25.79
CHAPTER 13. IMAGE CAPTURE
ICReturnScannerInUseByRemoteUser = -9926
Plugin Version: 14.3. Function: One of the error constants.
Notes: Scanner is being used by a local user.
13.25.80
ICReturnScanOperationCanceled = -9924
Plugin Version: 14.3. Function: One of the error constants.
Notes: The scan operation is canceled.
13.25.81
ICReturnSuccess = 0
Plugin Version: 14.3. Function: One of the error constants.
Notes: Operation successful.
13.25.82
ICReturnUploadFailed = -9935
Plugin Version: 14.3. Function: One of the error constants.
Notes: A non-specific error occurred while updownloading a file.
Chapter 14
ImageKit
14.1
class IKImageBrowserCellMBS
14.1.1
class IKImageBrowserCellMBS
Plugin Version: 13.1, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: The class for an
image browser cell.
Notes:
The IKImageBrowserCell class is used to display a cell conforming to the IKImageBrowserItem Protocol
protocol in an IKImageBrowserView.
This is an abstract class. You can’t create an instance, but you can get one from various plugin functions.
14.1.2
Methods
14.1.3
cellState as Integer
Plugin Version: 13.1, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: Returns the current
cell state of the receiver.
Notes:
The IKImageBrowserView creates thumbnails asynchronously. This method returns the current state.
Available in OS X v10.6 and later.
14.1.4
Constructor
Plugin Version: 13.1, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: The private constructor.
341
342
14.1.5
CHAPTER 14. IMAGEKIT
frame as NSRectMBS
Plugin Version: 13.1, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: Returns the receiver’s frame rectangle, which defines its position in its IKImageBrowserView.
Notes: Available in OS X v10.6 and later.
14.1.6
IKImageBrowserCellBackgroundLayer as string
Plugin Version: 13.1, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: One of the layer
types you can pass to layerForType.
Notes:
Layer displayed in the background.
Available in OS X v10.6 and later.
14.1.7
IKImageBrowserCellForegroundLayer as string
Plugin Version: 13.1, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: One of the layer
types you can pass to layerForType.
Notes:
Layer displayed in the foreground.
Available in OS X v10.6 and later.
14.1.8
IKImageBrowserCellPlaceHolderLayer as string
Plugin Version: 13.1, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: One of the layer
types you can pass to layerForType.
Notes:
Layer displayed as a placeholder when an image is not yet available.
Available in OS X v10.6 and later.
14.1.9
IKImageBrowserCellSelectionLayer as string
Plugin Version: 13.1, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: One of the layer
types you can pass to layerForType.
Notes:
14.1. CLASS IKIMAGEBROWSERCELLMBS
343
Layer displayed as the selection.
Available in OS X v10.6 and later.
14.1.10
imageAlignment as Integer
Plugin Version: 13.1, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: Returns the position
of the cell’s image in the frame.
14.1.11
imageBrowserView as IKImageBrowserViewMBS
Plugin Version: 13.1, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: Returns the view
the receiver uses to display the cell.
Notes: Available in OS X v10.6 and later.
14.1.12
imageContainerFrame as NSRectMBS
Plugin Version: 13.1, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: Returns the
receiver’s image container frame rectangle, which defines the position of the container of the thumbnail.
Notes:
The coordinates of image container frame, in the IKImageBrowserView coordinate space.
The image frame is computed automatically from the image container frame by taking in account the image
alignment and the image aspect ratio.
Subclasses can override this method to customize the position of the thumbnail container.
Available in OS X v10.6 and later.
14.1.13
imageFrame as NSRectMBS
Plugin Version: 13.1, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: Returns the
receiver’s image frame rectangle, which defines the position of the thumbnail in its IKImageBrowserView.
Notes:
Returns the coordinates of the frame, in the IKImageBrowserView coordinate space.
It is the developer’s responsibility to compute the imageFrame such that it lies entirely within the cell’s
frame rectangle.
Subclasses can override this method to customize the position of the thumbnail.
Available in OS X v10.6 and later.
344
14.1.14
CHAPTER 14. IMAGEKIT
indexOfRepresentedItem as Integer
Plugin Version: 13.1, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: Returns the index
of the receiver’s represented object in the datasource.
Notes: Available in OS X v10.6 and later.
14.1.15
isSelected as boolean
Plugin Version: 13.1, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: Returns whether
the cell is selected.
Notes:
Returns true if the cell is selected, otherwise false.
Subclasses should not override this method.
Available in OS X v10.6 and later.
14.1.16
layerForType(type as string) as CALayerMBS
Plugin Version: 13.1, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: Returns a layer for
the specified position.
Notes:
type: A string representing the layer location. See Cell Layer Positions for possible values.
Return the CALayer to display in the specified position.
Subclasses can override this method to add a Core Animation layer to the cell
Available in OS X v10.6 and later.
14.1.17
opacity as Double
Plugin Version: 13.1, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: Returns the opacity
of the receiver.
Notes:
Possible values are between 0.0 (transparent) and 1.0 (opaque).
Subclasses can override this method to customize the opacity of the cell.
Available in OS X v10.6 and later.
14.1.18
representedItem as Variant
Plugin Version: 13.1, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: Returns the
receiver’s represented object.
14.1. CLASS IKIMAGEBROWSERCELLMBS
345
Notes:
Subclasses should not override this method.
Available in OS X v10.6 and later.
14.1.19
selectionFrame as NSRectMBS
Plugin Version: 13.1, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: Returns the receiver’s
selection frame rectangle, which defines the position of the selection rectangle in its IKImageBrowserView.
Notes:
Subclasses can override this method to customize the position of the selection frame.
Available in OS X v10.6 and later.
14.1.20
subtitleFrame as NSRectMBS
Plugin Version: 13.1, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: Returns the
receiver’s subtitle frame rectangle.
Notes:
The coordinates of the subtitle frame, in the IKImageBrowserView coordinate space.
It is the developer’s responsibility to compute the subtitleFrame such that it lies entirely within the cell’s
frame rectangle.
Subclasses can override this method to customize the position of the subtitle.
Available in OS X v10.6 and later.
14.1.21
titleFrame as NSRectMBS
Plugin Version: 13.1, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: Returns the
receiver’s title frame rectangle.
Notes:
The coordinates of the title frame, in the IKImageBrowserView coordinate space.
It is the developer’s responsibility to compute the titleFrame such that it lies entirely within the cell’s frame
rectangle.
Subclasses can override this method to customize the position of the title.
Available in OS X v10.6 and later.
346
CHAPTER 14. IMAGEKIT
14.1.22
Properties
14.1.23
Handle as Integer
Plugin Version: 13.1, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: The internal object
reference.
Notes: (Read and Write property)
14.1.24
Constants
14.1.25
IKImageStateInvalid = 1
Plugin Version: 13.1. Function: One of the cell state constants.
Notes:
The thumbnail is invalid. For example, an unsupported image is provided.
Available in OS X v10.6 and later.
14.1.26
IKImageStateNoImage = 0
Plugin Version: 13.1. Function: One of the cell state constants.
Notes:
Returned until a thumbnail has been created from the represented object.
Available in OS X v10.6 and later.
14.1.27
IKImageStateReady = 2
Plugin Version: 13.1. Function: One of the cell state constants.
Notes:
The receiver’s represented object has been set and the cell is ready to display.
Available in OS X v10.6 and later.
14.2. CLASS IKIMAGEBROWSERITEMMBS
14.2
class IKImageBrowserItemMBS
14.2.1
class IKImageBrowserItemMBS
347
Plugin Version: 13.1, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: The class for items
in image browser.
14.2.2
Methods
14.2.3
Constructor(imageUID as string, imageRepresentationType as string,
imageRepresentation as Variant, imageVersion as Integer = 1, imageTitle as string = ””, imageSubtitle as string = ””, isSelectable as boolean
= true)
Plugin Version: 13.1, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: Creates a new item
with given values.
14.2.4
ItemWithCGImage(imageUID as string, Image as Variant, imageVersion as Integer = 1, imageTitle as string = ””, imageSubtitle as string
= ””, isSelectable as boolean = true) as IKImageBrowserItemMBS
Plugin Version: 13.1, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: Creates a new item
with given image.
14.2.5
ItemWithData(imageUID as string, Data as Memoryblock, imageVersion as Integer = 1, imageTitle as string = ””, imageSubtitle as string
= ””, isSelectable as boolean = true) as IKImageBrowserItemMBS
Plugin Version: 13.1, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: Creates a new item
with given data.
14.2.6
ItemWithFile(imageUID as string, file as folderitem, imageVersion as
Integer = 1, imageTitle as string = ””, imageSubtitle as string = ””,
isSelectable as boolean = true) as IKImageBrowserItemMBS
Plugin Version: 13.1, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: Creates a new item
with given file.
348
14.2.7
CHAPTER 14. IMAGEKIT
ItemWithNSImage(imageUID as string, Image as NSImageMBS, imageVersion as Integer = 1, imageTitle as string = ””, imageSubtitle as
string = ””, isSelectable as boolean = true) as IKImageBrowserItemMBS
Plugin Version: 13.1, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: Creates a new item
with given image.
14.2.8
ItemWithPath(imageUID as string, path as string, imageVersion as Integer = 1, imageTitle as string = ””, imageSubtitle as string = ””,
isSelectable as boolean = true) as IKImageBrowserItemMBS
Plugin Version: 13.1, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: Creates a new item
with given path.
14.2.9
ItemWithURL(imageUID as string, URL as string, imageVersion as Integer = 1, imageTitle as string = ””, imageSubtitle as string = ””,
isSelectable as boolean = true) as IKImageBrowserItemMBS
Plugin Version: 13.1, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: Creates a new item
with given URL.
14.2.10
Properties
14.2.11
Handle as Integer
Plugin Version: 13.1, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: The internal object
handle.
Notes: (Read and Write property)
14.2.12
imageRepresentation as Variant
Plugin Version: 13.1, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: Returns the image
to display.
Notes: (Read and Write computed property)
14.2. CLASS IKIMAGEBROWSERITEMMBS
14.2.13
349
imageRepresentationType as string
Plugin Version: 13.1, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: Returns the representation type of the image to display.
Notes: (Read and Write computed property)
14.2.14
imageSubtitle as string
Plugin Version: 13.1, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: Returns the display
subtitle of the image.
Notes: (Read and Write computed property)
14.2.15
imageTitle as string
Plugin Version: 13.1, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: Returns the display
title of the image.
Notes: (Read and Write computed property)
14.2.16
imageUID as string
Plugin Version: 13.1, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: Returns a unique
string that identifies the data source item.
Notes:
The image browser view uses this identifier to associate the data source item and its cache.
(Read and Write computed property)
14.2.17
imageVersion as Integer
Plugin Version: 13.1, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: Returns the version
of the item.
Notes:
The receiver can return a new version to let the image browser know that it should not use its cache for the
item.
(Read and Write computed property)
350
14.2.18
CHAPTER 14. IMAGEKIT
isSelectable as boolean
Plugin Version: 13.1, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: Returns whether
this item is selectable.
Notes:
True if the item is selectable; false otherwise.
(Read and Write computed property)
14.3. CONTROL IKIMAGEBROWSERVIEWCONTROLMBS
14.3
control IKImageBrowserViewControlMBS
14.3.1
control IKImageBrowserViewControlMBS
351
Plugin Version: 14.2, Console & Web: No, Mac: Yes, Win: No, Linux: No. Function: The control to wrap
a IKImageBrowserViewMBS.
14.3.2
Properties
14.3.3
Scrollview as NSScrollViewMBS
Plugin Version: 14.2, Console & Web: No, Mac: Yes, Win: No, Linux: No. Function: The scrollview we
embed the image browser view inside.
Notes: (Read only property)
14.3.4
View as IKImageBrowserViewMBS
Plugin Version: 14.2, Console & Web: No, Mac: Yes, Win: No, Linux: No. Function: The image browser
view.
Notes: (Read only property)
14.3.5
Events
14.3.6
backgroundWasRightClickedWithEvent(e as NSEventMBS)
Plugin Version: 14.2, Console & Web: No, Mac: Yes, Win: No, Linux: No. Function: Performs custom
tasks when the user right-clicks the image browser view background.
Notes:
event: The event that invoked the method.
This method signals that the user either right-clicked the background or left-clicked it with the Alt key
pressed. You can implement this method if you want to perform custom tasks at that time.
Available in OS X v10.5 and later.
352
14.3.7
CHAPTER 14. IMAGEKIT
BoundsChanged
Plugin Version: 17.1, Console & Web: No, Mac: Yes, Win: No, Linux: No. Function: The event called
when the bounds, but not the frame, changed.
14.3.8
cellWasDoubleClickedAtIndex(index as Integer)
Plugin Version: 14.2, Console & Web: No, Mac: Yes, Win: No, Linux: No. Function: Performs custom
tasks when the user double-clicks an item in the image browser view.
Notes:
index: The index of the cell.
This method signals that the user double-clicked an item in the image browser view. You can implement
this method if you want to perform custom tasks at that time.
Available in OS X v10.5 and later.
14.3.9
cellWasRightClickedAtIndex(index as Integer, e as NSEventMBS)
Plugin Version: 14.2, Console & Web: No, Mac: Yes, Win: No, Linux: No. Function: Performs custom
tasks when the user right-clicks an item in the image browser view.
Notes:
index: The index of the cell.
event: The event that invoked the method.
This method signals that the user either right-clicked an item in the browser or left-clicked the item with
the Alt key pressed. You can implement this method if you want to perform custom tasks at that time.
Available in OS X v10.5 and later.
14.3.10
concludeDragOperation(sender as NSDraggingInfoMBS)
Plugin Version: 14.2, Console & Web: No, Mac: Yes, Win: No, Linux: No. Function: Invoked when the
dragging operation is complete, signaling the receiver to perform any necessary clean-up.
Notes:
sender: The object sending the message; use it to get details about the dragging operation.
For this method to be invoked, the previous performDragOperation must have returned true.
14.3. CONTROL IKIMAGEBROWSERVIEWCONTROLMBS
353
The destination implements this method to perform any tidying up that it needs to do, such as updating its
visual representation now that it has incorporated the dragged data. This message is the last message sent
from sender to the destination during a dragging session.
If the sender object’s animatesToDestination property was set to true in prepareForDragOperation, then the
drag image is still visible. At this point you should draw the final visual representation in the view. When
this method returns, the drag image is removed form the screen. If your final visual representation matches
the visual representation in the drag, this is a seamless transition.
14.3.11
draggingEnded(sender as NSDraggingInfoMBS)
Plugin Version: 14.2, Console & Web: No, Mac: Yes, Win: No, Linux: No. Function: Implement this
event to be notified when a drag operation ends in some other destination.
Notes:
sender: The object sending the message; use it to get details about the dragging operation.
This method might be used by a destination doing auto-expansion in order to collapse any auto-expands.
14.3.12
draggingEntered(sender as NSDraggingInfoMBS) as Integer
Plugin Version: 14.2, Console & Web: No, Mac: Yes, Win: No, Linux: No. Function: Invoked when the
dragged image enters destination bounds or frame; delegate returns dragging operation to perform.
Notes:
sender: The object sending the message; use it to get details about the dragging operation.
Return one (and only one) of the dragging operation constants described in NSDragOperation in the NSDraggingInfo reference. The default return value (if this method is not implemented by the destination) is
the value returned by the previous draggingEntered: message.
Invoked when a dragged image enters the destination but only if the destination has registered for the pasteboard data type involved in the drag operation. Specifically, this method is invoked when the mouse pointer
enters the destination’s bounds rectangle (if it is a view object) or its frame rectangle (if it is a window object).
This method must return a value that indicates which dragging operation the destination will perform when
the image is released. In deciding which dragging operation to return, the method should evaluate the
overlap between both the dragging operations allowed by the source (obtained from sender with the draggingSourceOperationMask method) and the dragging operations and pasteboard data types the destination
itself supports.
If none of the operations is appropriate, this method should return NSDragOperationNone (this is the default
response if the method is not implemented by the destination). A destination will still receive draggingUp-
354
CHAPTER 14. IMAGEKIT
dated: and draggingExited: even if NSDragOperationNone is returned by this method.
14.3.13
draggingExited(sender as NSDraggingInfoMBS)
Plugin Version: 14.2, Console & Web: No, Mac: Yes, Win: No, Linux: No. Function: Invoked when the
dragged image exits the destination’s bounds rectangle (in the case of a view object) or its frame rectangle
(in the case of a window object).
Notes: sender: The object sending the message; use it to get details about the dragging operation.
14.3.14
draggingSourceOperationMaskForLocal(flag as boolean) as Integer
Plugin Version: 14.2, Console & Web: No, Mac: Yes, Win: No, Linux: No. Function: Returns an integer
bit mask indicating the types of dragging operations the source object will allow to be performed on the
dragged image’s data.
Notes:
(Deprecated in OS X v10.7. This method is informally deprecated. It is only called if the source does not
implement the NSDraggingSource protocol methods. This method will be formally deprecated in a future
OS release.)
isLocal: True indicates that the candidate destination object (the window or view over which the dragged
image is currently poised) is in the same application as the source, while a false value indicates that the
destination object is in a different application.
A mask, created by combining the dragging operations listed in the NSDragOperation section of NSDraggingInfo protocol reference using the C bitwise OR operator.If the source does not permit any dragging
operations, it should return NSDragOperationNone.
If not implemented, the default value is NSDragOperationCopy | NSDragOperationLink | NSDragOperationGeneric | NSDragOperationPrivate.
Available in OS X v10.0 and later. Deprecated in OS X v10.7.
14.3.15
draggingUpdated(sender as NSDraggingInfoMBS) as Integer
Plugin Version: 14.2, Console & Web: No, Mac: Yes, Win: No, Linux: No. Function: Invoked periodically
as the image is held within the destination area, allowing modification of the dragging operation or mousepointer position.
Notes:
14.3. CONTROL IKIMAGEBROWSERVIEWCONTROLMBS
355
sender: The object sending the message; use it to get details about the dragging operation.
Returns one (and only one) of the dragging operation constants described in NSDragOperation in the NSDraggingInfo reference. The default return value (if this method is not implemented by the destination) is
the value returned by the previous draggingEntered: message.
For this to be invoked, the destination must have registered for the pasteboard data type involved in the
drag operation. The messages continue until the image is either released or dragged out of the window or view.
This method provides the destination with an opportunity to modify the dragging operation depending on
the position of the mouse pointer inside of the destination view or window object. For example, you may have
several graphics or areas of text contained within the same view and wish to tailor the dragging operation,
or to ignore the drag event completely, depending upon which object is underneath the mouse pointer at the
time when the user releases the dragged image and the performDragOperation method is invoked.
You typically examine the contents of the pasteboard in the draggingEntered method, where this examination is performed only once, rather than in the draggingUpdated method, which is invoked multiple times.
Only one destination at a time receives a sequence of draggingUpdated messages. If the mouse pointer is
within the bounds of two overlapping views that are both valid destinations, the uppermost view receives
these messages until the image is either released or dragged out.
14.3.16
EnableMenuItems
Plugin Version: 17.1, Console & Web: No, Mac: Yes, Win: Yes, Linux: Yes. Function: The event where
you can enable menu items.
14.3.17
FrameChanged
Plugin Version: 17.1, Console & Web: No, Mac: Yes, Win: No, Linux: No. Function: The event called
when the frame changed.
14.3.18
GotFocus
Plugin Version: 16.5, Console & Web: No, Mac: Yes, Win: No, Linux: No. Function: The control itself
got focus.
Notes: This only fires if the control itself got focus and not a sub control.
356
14.3.19
CHAPTER 14. IMAGEKIT
groupAtIndex(index as Integer) as Dictionary
Plugin Version: 14.2, Console & Web: No, Mac: Yes, Win: No, Linux: No. Function: Returns the group
at the specified index.
Notes:
index: The index of the group you want to retrieve.
Returns a dictionary that defines the group. The keys in this dictionary can be any of the following constants:
IKImageBrowserGroupStyle, IKImageBrowserGroupBackgroundColorKey, IKImageBrowserGroupTitleKey,
and IKImageBrowserGroupRangeKey. For more information on these constants, see IKImageBrowserView
Class Reference.
This method is optional.
Available in OS X v10.5 and later.
14.3.20
itemAtIndex(index as Integer) as IKImageBrowserItemMBS
Plugin Version: 14.2, Console & Web: No, Mac: Yes, Win: No, Linux: No. Function: Returns an object
for the item in an image browser view that corresponds to the specified index.
Notes:
index: The index of the item you want to retrieve.
Return an IKImageBrowserItem object.
Your data source must implement this method. The returned object must implement the required methods
of the IKImageBrowserItem protocol.
Available in OS X v10.5 and later.
14.3.21
LostFocus
Plugin Version: 16.5, Console & Web: No, Mac: Yes, Win: No, Linux: No. Function: The control lost
focus.
Notes: This only fires if the control itself lost focus and not a sub control.
14.3.22
MenuAction(HitItem as MenuItem) As Boolean
Plugin Version: 17.1, Console & Web: No, Mac: Yes, Win: No, Linux: No. Function: Called when a
menuitem is choosen.
14.3. CONTROL IKIMAGEBROWSERVIEWCONTROLMBS
357
Notes: This allows the control to react on its relevant menu items. Please return true if you handled it or
false to give others a chance.
14.3.23
MouseDown(x as Integer, y as Integer, Modifiers as Integer) As Boolean
Plugin Version: 17.1, Console & Web: No, Mac: Yes, Win: No, Linux: No. Function: The mouse button
was pressed inside the controls region at the location passed in to x, y.
Notes:
The coordinates x and y are local to the control, i.e. they represent the position of the mouse click relative
to the upper-left corner or the Control.
Return True if you are going to handle the MouseDown. In such a case:
• The Action event, if any, will not execute and the state of the object will not change.
• You will receive the MouseDrag and MouseUp events.
If you return False, the system handles the MouseDown so the above event handlers do not get called.
14.3.24
MouseDrag(x as Integer, y as Integer)
Plugin Version: 17.1, Console & Web: No, Mac: Yes, Win: No, Linux: No. Function: This event fires
continuously after the mouse button was pressed inside the Control.
Notes:
Mouse location is local to the control passed in to x, y.
As this event is fired continuously (hundreds of time per second), it is your responsibility to determine if the
mouse has really moved.
14.3.25
MouseUp(x as Integer, y as Integer)
Plugin Version: 17.1, Console & Web: No, Mac: Yes, Win: No, Linux: No. Function: The mouse button
was released.
Notes: Use the x and y parameters to determine if the mouse button was released within the control’s
boundaries.
358
14.3.26
CHAPTER 14. IMAGEKIT
moveItemsAtIndexes(indexes as NSIndexSetMBS, destinationIndex as
Integer) as boolean
Plugin Version: 14.2, Console & Web: No, Mac: Yes, Win: No, Linux: No. Function: Signals that the
specified items should be moved to the specified destination.
Notes:
indexes: The indexes of the items that should be reordered.
destinationIndex: The starting index of the destination the items should be moved to.
Returns true if successful; false otherwise.
This method is optional. It is invoked by the image browser view after Image Kit determines that a reordering operation should be applied. The data source should update itself by reordering its elements.
Available in OS X v10.5 and later.
14.3.27
numberOfGroups as Integer
Plugin Version: 14.2, Console & Web: No, Mac: Yes, Win: No, Linux: No. Function: Returns the number
of groups in an image browser view.
Notes:
Return the number of groups.
This method is optional.
Available in OS X v10.5 and later.
14.3.28
numberOfItems as Integer
Plugin Version: 14.2, Console & Web: No, Mac: Yes, Win: No, Linux: No. Function: Returns the number
of records managed by the data source object.
Notes:
Return the number of records managed by the image browser view.
Your data source must implement this method. An IKImageView object uses this method to determine how
many cells it should create and display.
Available in OS X v10.5 and later.
14.3. CONTROL IKIMAGEBROWSERVIEWCONTROLMBS
14.3.29
359
performDragOperation(sender as NSDraggingInfoMBS) as boolean
Plugin Version: 14.2, Console & Web: No, Mac: Yes, Win: No, Linux: No. Function: Invoked after the
released image has been removed from the screen, signaling the receiver to import the pasteboard data.
Notes:
sender: The object sending the message; use it to get details about the dragging operation.
Returns if the destination accepts the data, it returns true; otherwise it returns false. The default is to
return false.
For this method to be invoked, the previous prepareForDragOperation message must have returned true.
The destination should implement this method to do the real work of importing the pasteboard data represented by the image.
If the sender object’s animatesToDestination was set to true in prepareForDragOperation, then setup any
animation to arrange space for the drag items to animate to. Also at this time, enumerate through the
dragging items to set their destination frames and destination images.
14.3.30
prepareForDragOperation(sender as NSDraggingInfoMBS) as boolean
Plugin Version: 14.2, Console & Web: No, Mac: Yes, Win: No, Linux: No. Function: Invoked when the
image is released, allowing the receiver to agree to or refuse drag operation.
Notes:
sender: The object sending the message; use it to get details about the dragging operation.
Return true if the receiver agrees to perform the drag operation and false if not.
This method is invoked only if the most recent draggingEntered or draggingUpdated event returned an acceptable drag-operation value.
If you want the drag items to animate from their current location on screen to their final location in your
view, set the sender object’s animatesToDestination property to true in your implementation of this event.
14.3.31
removeItemsAtIndexes(indexes as NSIndexSetMBS)
Plugin Version: 14.2, Console & Web: No, Mac: Yes, Win: No, Linux: No. Function: Signals that a
remove operation should be applied to the specified items.
Notes:
360
CHAPTER 14. IMAGEKIT
indexes: The indexes of the items that should be removed.
This method is optional. It is invoked by the image browser after Image Kit determines that a remove
operation should be applied. In response, the data source should update itself by removing the specified
items.
Available in OS X v10.5 and later.
14.3.32
ScaleFactorChanged(NewFactor as Double)
Plugin Version: 17.1, Console & Web: No, Mac: Yes, Win: No, Linux: No. Function: The backing store
scale factor has changed.
Notes: Please invalidate any cached bitmaps or other relevant state.
14.3.33
selectionDidChange
Plugin Version: 14.2, Console & Web: No, Mac: Yes, Win: No, Linux: No. Function: Performs custom
tasks when the selection changes.
Notes:
This method signals that the user changes the selection in the image browser view. You can implement this
method if you want to perform custom tasks at that time.
Available in OS X v10.5 and later.
14.3.34
updateDraggingItemsForDrag(sender as NSDraggingInfoMBS)
Plugin Version: 14.2, Console & Web: No, Mac: Yes, Win: No, Linux: No. Function: Invoked when the
dragging images should be changed.
Notes:
sender: The object sending the message; use this object to get details about the dragging operation.
While a destination may change the dragging images at any time, it is recommended to wait until this
method is called before updating the dragging images.
This allows the system to delay changing the dragging images until it is likely that the user will drop on
this destination. Otherwise, the dragging images will change too often during the drag which would be
distracting to the user.
During enumerateDraggingItemsWithOptions you may set non-acceptable drag items images to nil to hide
them or use the enumeration option of NSDraggingItemEnumerationClearNonenumeratedImages If there
14.3. CONTROL IKIMAGEBROWSERVIEWCONTROLMBS
361
are items that you hide, then after enumeration, you need to set the numberOfValidItemsForDrop to the
number of non-hidden drag items. However, if the valid item count is 0, then it is better to return NSDragOperationNone from your implementation of draggingEntered and, or draggingUpdated instead of hiding all
drag items during enumeration.
Available in OS X v10.7 and later.
14.3.35
wantsPeriodicDraggingUpdates as boolean
Plugin Version: 14.2, Console & Web: No, Mac: Yes, Win: No, Linux: No. Function: Asks the destination
object whether it wants to receive periodic draggingUpdated events.
Notes:
Returns true if the destination wants to receive periodic draggingUpdated messages, false otherwise.
If the destination returns false, these messages are sent only when the mouse moves or a modifier flag changes.
Otherwise the destination gets the default behavior, where it receives periodic dragging-updated events even
if nothing changes.
14.3.36
writeItemsAtIndexes(indexes as NSIndexSetMBS, pasteboard as NSPasteboardMBS) as Integer
Plugin Version: 14.2, Console & Web: No, Mac: Yes, Win: No, Linux: No. Function: Signals that a drag
should begin.
Notes:
itemIndexes: The indexes of the items that should be dragged.
pasteboard: The pasteboard to copy the items to.
Returns the number of items written to the pasteboard.
This method is optional. It is invoked after Image Kit determines that a drag should begin, but before the
drag has been started.
Available in OS X v10.5 and later.
362
CHAPTER 14. IMAGEKIT
14.4
class IKImageBrowserViewMBS
14.4.1
class IKImageBrowserViewMBS
Plugin Version: 13.1, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: The IKImageBrowserView class is a view for displaying and browsing a large amount of images and movies efficiently.
Notes:
Available in OS X v10.5 and later.
Subclass of the NSViewMBS class.
14.4.2
Methods
14.4.3
cellForItemAtIndex(index as Integer) as IKImageBrowserCellMBS
Plugin Version: 13.1, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: Returns the browser
cell for the item at the specified index.
Notes:
Subclasses must not override this method.
Available in OS X v10.6 and later.
14.4.4
collapseGroupAtIndex(index as Integer)
Plugin Version: 13.1, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: Collapses a group
at the specified index.
Notes: index: The index of the group you want to collapse.
14.4.5
columnIndexesInRect(rect as NSRectMBS) as NSIndexSetMBS
Plugin Version: 13.1, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: Returns the column
indexes in the specified rectangle.
Notes:
rect: The rectangle in the view’s coordinate system.
Returns an index set containing the cell indexes.
Available in OS X v10.6 and later.
14.4. CLASS IKIMAGEBROWSERVIEWMBS
14.4.6
363
Constructor
Plugin Version: 13.1, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: Creates a new
control with size 100/100 and position 0/0
Example:
dim t as new IKImageBrowserViewMBS
Notes: On success the handle property is not zero.
See also:
• 14.4.7 Constructor(Handle as Integer)
363
• 14.4.8 Constructor(left as Double, top as Double, width as Double, height as Double)
363
14.4.7
Constructor(Handle as Integer)
Plugin Version: 13.1, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: Creates an object
based on the given IKImageBrowserView handle.
Example:
dim t as new IKImageBrowserViewMBS(0, 0, 100, 100)
dim v as new IKImageBrowserViewMBS(t.handle)
MsgBox str(v.Bounds.Width)+” x ”+str(v.Bounds.Height)
Notes: The handle is casted to a IKImageBrowserView and the plugin retains this handle.
See also:
• 14.4.6 Constructor
363
• 14.4.8 Constructor(left as Double, top as Double, width as Double, height as Double)
363
14.4.8
Constructor(left as Double, top as Double, width as Double, height as
Double)
Plugin Version: 13.1, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: Creates a new
control with the given size and position.
Example:
dim x as new IKImageBrowserViewMBS(0, 0, 100, 20)
364
CHAPTER 14. IMAGEKIT
Notes: On success the handle property is not zero.
See also:
• 14.4.6 Constructor
363
• 14.4.7 Constructor(Handle as Integer)
363
14.4.9
Destructor
Plugin Version: 13.1, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: The destructor.
14.4.10
dropOperation as Integer
Plugin Version: 13.1, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: Returns the current
drop operation.
Notes:
Returns IKImageBrowserDropOn if the drop occurs on an item, otherwise IKImageBrowserDropBefore.
The returned value is valid when a drop occurred and until next drop.
For example, given a browser with N cells , a cell of N-1 and operation of IKImageBrowserDropOn would
specify a drop on the last cell. To specify a drop after the last cell, one would use an index of N and
IKImageBrowserDropBefore for the operation.
Available in OS X v10.6 and later.
14.4.11
expandGroupAtIndex(index as Integer)
Plugin Version: 13.1, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: Expands a group at
the specified index.
Notes:
index: The index of the group you want to expand.
Available in OS X v10.5 and later.
14.4.12
getValue(name as String) as Variant
Plugin Version: 13.1, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: Queries a value for
a given key.
14.4. CLASS IKIMAGEBROWSERVIEWMBS
14.4.13
365
IKImageBrowserBackgroundColorKey as string
Plugin Version: 13.1, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: One of the keys for
image browser view options.
Notes:
A key for the background color of the image browser view. The associated value is a NSColorMBS object.
Available in OS X v10.5 and later.
14.4.14
IKImageBrowserCellsHighlightedTitleAttributesKey as string
Plugin Version: 13.1, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: One of the keys for
image browser view options.
Notes:
A key for the highlighted title attribute for an item in the image browser view. The associated value is a
Dictionary.
Available in OS X v10.5 and later.
14.4.15
IKImageBrowserCellsOutlineColorKey as string
Plugin Version: 13.1, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: One of the keys for
image browser view options.
Notes:
A key for the outline color for an item in the image browser view. The associated value is an NSColorMBS
object.
Available in OS X v10.5 and later.
14.4.16
IKImageBrowserCellsSubtitleAttributesKey as string
Plugin Version: 13.1, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: One of the keys for
image browser view options.
Notes:
A key for a subtitle attribute for an item in the image browser view. The associated value is a dictionary.
Available in OS X v10.5 and later.
366
14.4.17
CHAPTER 14. IMAGEKIT
IKImageBrowserCellsTitleAttributesKey as string
Plugin Version: 13.1, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: One of the keys for
image browser view options.
Example:
dim Imagebrowser as IKImageBrowserViewMBS // your control
dim d as new Dictionary
d.Value(NSAttributedStringMBS.NSForegroundColorAttributeName) = NSColorMBS.redColor
Imagebrowser.setValue Imagebrowser.IKImageBrowserCellsTitleAttributesKey, d
Notes:
A key for title attribute of an item in the image browser view. The associated value is a dDictionary.
Available in OS X v10.5 and later.
14.4.18
IKImageBrowserCGImageRepresentationType as string
Plugin Version: 13.1, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: One of the image
representation types.
Notes: A CGImageRef object.
14.4.19
IKImageBrowserCGImageSourceRepresentationType as string
Plugin Version: 13.1, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: One of the image
representation types.
Notes: A CGImageSourceRef object.
14.4.20
IKImageBrowserGroupBackgroundColorKey as string
Plugin Version: 13.1, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: One of the group
attribute keys.
Notes:
A key for the background color of a group. The associated value is an NSColor object. This color is used
only for the bezel style.
Available in OS X v10.5 and later.
14.4. CLASS IKIMAGEBROWSERVIEWMBS
14.4.21
367
IKImageBrowserGroupFooterLayer as string
Plugin Version: 13.1, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: One of the group
attribute keys.
Notes:
A key for the header layer of the group. The associated value is a CALayer.
Available in OS X v10.6 and later.
14.4.22
IKImageBrowserGroupHeaderLayer as string
Plugin Version: 13.1, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: One of the group
attribute keys.
Notes:
A key for the header layer of the group. The associated value is a CALayer.
Available in OS X v10.6 and later.
14.4.23
IKImageBrowserGroupRangeKey as string
Plugin Version: 13.1, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: One of the group
attribute keys.
Notes:
A key for the range of a group. The associated value is a NSRangeMBS. This is required if the view uses
grouping
Available in OS X v10.5 and later.
14.4.24
IKImageBrowserGroupStyleKey as string
Plugin Version: 13.1, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: One of the group
attribute keys.
Notes:
A key for the style of a group. The associated value is one of the constants defined in ”Group Style Attributes”.
Available in OS X v10.5 and later.
368
14.4.25
CHAPTER 14. IMAGEKIT
IKImageBrowserGroupTitleKey as string
Plugin Version: 13.1, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: One of the group
attribute keys.
Notes:
A key for the title of a group. The associated value is a string. This string is used for the disclosure style
only.
Available in OS X v10.5 and later.
14.4.26
IKImageBrowserIconRefPathRepresentationType as string
Plugin Version: 13.1, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: One of the image
representation types.
Notes: A path to an icon.
14.4.27
IKImageBrowserIconRefRepresentationType as string
Plugin Version: 13.1, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: One of the image
representation types.
Notes: An icon.
14.4.28
IKImageBrowserNSBitmapImageRepresentationType as string
Plugin Version: 13.1, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: One of the image
representation types.
Notes: An NSBitmapImageRep object.
14.4.29
IKImageBrowserNSDataRepresentationType as string
Plugin Version: 13.1, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: One of the image
representation types.
Notes: Value for this key is a memoryblock.
14.4.30
IKImageBrowserNSImageRepresentationType as string
Plugin Version: 13.1, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: One of the image
representation types.
14.4. CLASS IKIMAGEBROWSERVIEWMBS
369
Notes: An NSImage object.
14.4.31
IKImageBrowserNSURLRepresentationType as string
Plugin Version: 13.1, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: One of the image
representation types.
Notes: An NSURL object.
14.4.32
IKImageBrowserPathRepresentationType as string
Plugin Version: 13.1, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: One of the image
representation types.
Notes: A path representation (string).
14.4.33
IKImageBrowserPDFPageRepresentationType as string
Plugin Version: 13.1, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: One of the image
representation types.
Notes: A PDFPage instance or a CGPDFPageRef.
14.4.34
IKImageBrowserQCCompositionPathRepresentationType as string
Plugin Version: 13.1, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: One of the image
representation types.
Notes: A path (String) or URL (NSURL) to a Quartz Composer composition.
14.4.35
IKImageBrowserQCCompositionRepresentationType as string
Plugin Version: 13.1, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: One of the image
representation types.
Notes: A QCComposition object.
14.4.36
IKImageBrowserQTMoviePathRepresentationType as string
Plugin Version: 13.1, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: One of the image
representation types.
370
CHAPTER 14. IMAGEKIT
Notes: A path (string) or URL to a QuickTime movie.
14.4.37
IKImageBrowserQTMovieRepresentationType as string
Plugin Version: 13.1, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: One of the image
representation types.
Notes: A QTMovie object.
14.4.38
IKImageBrowserQuickLookPathRepresentationType as string
Plugin Version: 13.1, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: One of the image
representation types.
Notes: A path (string) or URL (NSURL) to load data using QuickLook.
14.4.39
IKImageBrowserSelectionColorKey as string
Plugin Version: 13.1, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: One of the keys for
image browser view options.
Notes:
A key for the color that indicates a selection. The associated value is an NSColorMBS object.
Available in OS X v10.5 and later.
14.4.40
indexAtLocationOfDroppedItem as Integer
Plugin Version: 13.1, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: Returns the index
of the cell where the drop operation occurred.
Notes:
Returns the index of the cell where the drop operation occurred.
The returned index is valid until the next drop occurs.
Available in OS X v10.5 and later.
14.4.41
indexOfItemAtPoint(point as NSPointMBS) as Integer
Plugin Version: 13.1, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: Returns the index
of the item at the specified location.
Notes: Returns the index of the item or NSNotFound (-1) if no item at this location.
14.4. CLASS IKIMAGEBROWSERVIEWMBS
14.4.42
371
isGroupExpandedAtIndex(index as Integer) as boolean
Plugin Version: 13.1, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: Returns whether
the group at the provided index is expanded.
Notes: Return true if the group is expanded; false otherwise.
14.4.43
itemFrameAtIndex(index as Integer) as NSRectMBS
Plugin Version: 13.1, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: Returns the frame
rectangle for the item located at the specified index.
Notes:
index: The index of the item whose frame rectangle you want to obtain.
Return the frame rectangle of the item.
14.4.44
newCellForRepresentedItem(item as IKImageBrowserItemMBS) as IKImageBrowserCellMBS
Plugin Version: 13.1, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: Returns the cell to
use for the specified item.
Notes:
Subclasses can override this method to customize the appearance of the cell that will represent anItem.
Available in OS X v10.6 and later.
14.4.45
numberOfColumns as Integer
Plugin Version: 13.1, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: Returns the current
number of columns.
Notes: Available in OS X v10.6 and later.
14.4.46
numberOfRows as Integer
Plugin Version: 13.1, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: Returns the current
number of rows.
Notes: Available in OS X v10.6 and later.
372
14.4.47
CHAPTER 14. IMAGEKIT
rectOfColumn(columnIndex as Integer) as NSRectMBS
Plugin Version: 13.1, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: Returns the
rectangle containing the specified column.
Notes:
Return a rectangle containing the column. Specified in the view’s coordinate system.
Available in OS X v10.6 and later.
14.4.48
rectOfRow(rowIndex as Integer) as NSRectMBS
Plugin Version: 13.1, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: Returns the
rectangle containing the specified row.
Notes:
Returns a rectangle containing the column. Specified in the view’s coordinate system.
Available in OS X v10.6 and later.
14.4.49
reloadData
Plugin Version: 13.1, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: Marks the receiver
as needing its data reloaded.
14.4.50
rowIndexesInRect(rect as NSRectMBS) as NSIndexSetMBS
Plugin Version: 13.1, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: Returns the row
indexes in the specified rectangle.
Notes:
rect: A rectangle in the view’s coordinate system.
Returns an index set containing the item indexes.
Available in OS X v10.6 and later.
14.4.51
scrollIndexToVisible(index as Integer)
Plugin Version: 13.1, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: Scrolls the receiver
to the item at the specified index.
14.4. CLASS IKIMAGEBROWSERVIEWMBS
14.4.52
373
selectionIndexes as NSIndexSetMBS
Plugin Version: 13.1, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: Returns the indexes
of the selected cells.
14.4.53
setDropIndex(index as Integer, operation as Integer)
Plugin Version: 13.1, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: Allows the class to
retarget the drop action.
Notes:
index: The requested drop index.
operation: The requested drop operation. The possible values are described in IKImageBrowserDropOperation.
For example, To specify a drop on the second item, one would specify index as 1, and operation as IKImageBrowserDropOn. To specify a drop after the last item, one would specify index as the number of items
and operation as IKImageBrowserDropBefore.
Passing a value of 1 for index, and IKImageBrowserDropOn as the operation causes the entire browser view
to be highlighted rather than a specific item. This is useful if the data displayed by the receiver does not
allow the user to drop items at a specific item location.
14.4.54
setSelectionIndexes(indexes as NSIndexSetMBS, extendSelection as boolean
= false)
Plugin Version: 13.1, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: Selects cells at the
specified indexes.
Notes:
indexes: The indexes of the cells you want to select.
extendSelection: A boolean value that specifies whether to extend the current selection. Pass true to extends
the selection; false replaces the current selection.
Available in OS X v10.5 and later.
14.4.55
setValue(name as String, value as Variant)
Plugin Version: 13.1, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: Sets a value for a
given key.
374
14.4.56
CHAPTER 14. IMAGEKIT
visibleItemIndexes as NSIndexSetMBS
Plugin Version: 13.1, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: Returns the indexes
of the view’s currently visible items.
Notes: Available in OS X v10.6 and later.
14.4.57
Properties
14.4.58
allowsDroppingOnItems as boolean
Plugin Version: 13.1, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: Whether the user
can drop on items.
Notes:
True if the user is able to drop on items, otherwise false.
Available in OS X v10.6 and later.
(Read and Write computed property)
14.4.59
allowsEmptySelection as boolean
Plugin Version: 13.1, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: Whether an empty
selection is allowed.
Notes: (Read and Write computed property)
14.4.60
allowsMultipleSelection as boolean
Plugin Version: 13.1, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: Whether the user
can select more than one cell at a time.
Notes: (Read and Write computed property)
14.4.61
allowsReordering as boolean
Plugin Version: 13.1, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: Whether the user
can reorder items.
Notes: (Read and Write computed property)
14.4. CLASS IKIMAGEBROWSERVIEWMBS
14.4.62
375
animates as boolean
Plugin Version: 13.1, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: Whether the receiver
animates reordering and changes of the data source.
Notes: (Read and Write computed property)
14.4.63
backgroundLayer as CALayerMBS
Plugin Version: 13.1, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: The Core Animation
layer used as the view’s background.
Notes:
The background layer can have sublayers. Additionally, the layers can also contain animations.
The layer is optional.
Available in OS X v10.6 and later.
(Read and Write computed property)
14.4.64
canControlQuickLookPanel as boolean
Plugin Version: 13.1, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: Whether the view
can automatically take control of the QuickLook panel.
Notes:
When the browser view displays the QuickLook panel it sets itself as the QuickLook datasource. If the
browser cells returned by the datasource return items that are URLs or paths, then the QuickLook panel
will display the image at that location. Otherwise, the browser cell must implement the QLPreviewItem
protocol and return the requested URL for the custom cell.
Available in OS X v10.6 and later.
(Read and Write computed property)
14.4.65
cellSize as NSSizeMBS
Plugin Version: 13.1, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: The cell size.
Notes:
You must use CellSize or ZoomValue, but not both. Setting the zoom value changes the cell size, and vice
versa.
Available in OS X v10.5 and later.
(Read and Write computed property)
376
14.4.66
CHAPTER 14. IMAGEKIT
cellsStyleMask as Integer
Plugin Version: 13.1, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: The appearance
style of the cells.
Notes: (Read and Write computed property)
14.4.67
constrainsToOriginalSize as boolean
Plugin Version: 13.1, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: Whether the receiver
constrains the cell’s image to its original size.
Notes:
The default value is false.
(Read and Write computed property)
14.4.68
contentResizingMask as Integer
Plugin Version: 13.1, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: The content resizing
mask, which determines how its content is resized while zooming.
Notes:
You specify a mask by combining any of the following options using the bitwise OR operator: NSViewWidthSizable (2), NSViewHeightSizable (16). Other values are ignored.
(Read and Write computed property)
14.4.69
foregroundLayer as CALayerMBS
Plugin Version: 13.1, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: Returns the
foreground Core Animation layer
Notes:
Returns a CALayer instance.
Available in OS X v10.6 and later.
(Read and Write computed property)
14.4.70
intercellSpacing as NSSizeMBS
Plugin Version: 13.1, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: Returns the spacing
between cells in the view.
Notes:
14.4. CLASS IKIMAGEBROWSERVIEWMBS
377
Returns the vertical and horizontal spacing between cells.
Available in OS X v10.6 and later.
(Read and Write computed property)
14.4.71
zoomValue as Double
Plugin Version: 13.1, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: The zoom value.
Notes:
The zoom value. This value should be greater or equal to zero and less or equal than one. A zoom value of
zero corresponds to the minimum size (40x40 pixels). A zoom value of one means images fits the browser
bounds. Other values are interpolated.
Discussion
You must use ZoomValue or CellSize, but not both. Setting the zoom value changes the cell size, and vice
versa.
Available in OS X v10.5 and later.
(Read and Write computed property)
14.4.72
Events
14.4.73
backgroundWasRightClickedWithEvent(e as NSEventMBS)
Plugin Version: 13.1, Console & Web: No, Mac: Yes, Win: No, Linux: No. Function: Performs custom
tasks when the user right-clicks the image browser view background.
Notes:
event: The event that invoked the method.
This method signals that the user either right-clicked the background or left-clicked it with the Alt key
pressed. You can implement this method if you want to perform custom tasks at that time.
Available in OS X v10.5 and later.
14.4.74
cellWasDoubleClickedAtIndex(index as Integer)
Plugin Version: 13.1, Console & Web: No, Mac: Yes, Win: No, Linux: No. Function: Performs custom
tasks when the user double-clicks an item in the image browser view.
Notes:
index: The index of the cell.
This method signals that the user double-clicked an item in the image browser view. You can implement
this method if you want to perform custom tasks at that time.
378
CHAPTER 14. IMAGEKIT
Available in OS X v10.5 and later.
14.4.75
cellWasRightClickedAtIndex(index as Integer, e as NSEventMBS)
Plugin Version: 13.1, Console & Web: No, Mac: Yes, Win: No, Linux: No. Function: Performs custom
tasks when the user right-clicks an item in the image browser view.
Notes:
index: The index of the cell.
event: The event that invoked the method.
This method signals that the user either right-clicked an item in the browser or left-clicked the item with
the Alt key pressed. You can implement this method if you want to perform custom tasks at that time.
Available in OS X v10.5 and later.
14.4.76
concludeDragOperation(sender as NSDraggingInfoMBS)
Plugin Version: 13.1, Console & Web: No, Mac: Yes, Win: No, Linux: No. Function: Invoked when the
dragging operation is complete, signaling the receiver to perform any necessary clean-up.
Notes:
sender: The object sending the message; use it to get details about the dragging operation.
For this method to be invoked, the previous performDragOperation must have returned true.
The destination implements this method to perform any tidying up that it needs to do, such as updating its
visual representation now that it has incorporated the dragged data. This message is the last message sent
from sender to the destination during a dragging session.
If the sender object’s animatesToDestination property was set to true in prepareForDragOperation, then the
drag image is still visible. At this point you should draw the final visual representation in the view. When
this method returns, the drag image is removed form the screen. If your final visual representation matches
the visual representation in the drag, this is a seamless transition.
14.4.77
draggingEnded(sender as NSDraggingInfoMBS)
Plugin Version: 13.1, Console & Web: No, Mac: Yes, Win: No, Linux: No. Function: Implement this
event to be notified when a drag operation ends in some other destination.
Notes:
14.4. CLASS IKIMAGEBROWSERVIEWMBS
379
sender: The object sending the message; use it to get details about the dragging operation.
This method might be used by a destination doing auto-expansion in order to collapse any auto-expands.
14.4.78
draggingEntered(sender as NSDraggingInfoMBS) as Integer
Plugin Version: 13.1, Console & Web: No, Mac: Yes, Win: No, Linux: No. Function: Invoked when the
dragged image enters destination bounds or frame; delegate returns dragging operation to perform.
Notes:
sender: The object sending the message; use it to get details about the dragging operation.
Return one (and only one) of the dragging operation constants described in NSDragOperation in the NSDraggingInfo reference. The default return value (if this method is not implemented by the destination) is
the value returned by the previous draggingEntered: message.
Invoked when a dragged image enters the destination but only if the destination has registered for the pasteboard data type involved in the drag operation. Specifically, this method is invoked when the mouse pointer
enters the destination’s bounds rectangle (if it is a view object) or its frame rectangle (if it is a window object).
This method must return a value that indicates which dragging operation the destination will perform when
the image is released. In deciding which dragging operation to return, the method should evaluate the
overlap between both the dragging operations allowed by the source (obtained from sender with the draggingSourceOperationMask method) and the dragging operations and pasteboard data types the destination
itself supports.
If none of the operations is appropriate, this method should return NSDragOperationNone (this is the default
response if the method is not implemented by the destination). A destination will still receive draggingUpdated: and draggingExited: even if NSDragOperationNone is returned by this method.
14.4.79
draggingExited(sender as NSDraggingInfoMBS)
Plugin Version: 13.1, Console & Web: No, Mac: Yes, Win: No, Linux: No. Function: Invoked when the
dragged image exits the destination’s bounds rectangle (in the case of a view object) or its frame rectangle
(in the case of a window object).
Notes: sender: The object sending the message; use it to get details about the dragging operation.
14.4.80
draggingSourceOperationMaskForLocal(flag as boolean) as Integer
Plugin Version: 13.5, Console & Web: No, Mac: Yes, Win: No, Linux: No. Function: Returns an integer
bit mask indicating the types of dragging operations the source object will allow to be performed on the
380
CHAPTER 14. IMAGEKIT
dragged image’s data.
Notes:
(Deprecated in OS X v10.7. This method is informally deprecated. It is only called if the source does not
implement the NSDraggingSource protocol methods. This method will be formally deprecated in a future
OS release.)
isLocal: True indicates that the candidate destination object (the window or view over which the dragged
image is currently poised) is in the same application as the source, while a false value indicates that the
destination object is in a different application.
A mask, created by combining the dragging operations listed in the NSDragOperation section of NSDraggingInfo protocol reference using the C bitwise OR operator.If the source does not permit any dragging
operations, it should return NSDragOperationNone.
If not implemented, the default value is NSDragOperationCopy | NSDragOperationLink | NSDragOperationGeneric | NSDragOperationPrivate.
Available in OS X v10.0 and later. Deprecated in OS X v10.7.
14.4.81
draggingUpdated(sender as NSDraggingInfoMBS) as Integer
Plugin Version: 13.1, Console & Web: No, Mac: Yes, Win: No, Linux: No. Function: Invoked periodically
as the image is held within the destination area, allowing modification of the dragging operation or mousepointer position.
Notes:
sender: The object sending the message; use it to get details about the dragging operation.
Returns one (and only one) of the dragging operation constants described in NSDragOperation in the NSDraggingInfo reference. The default return value (if this method is not implemented by the destination) is
the value returned by the previous draggingEntered: message.
For this to be invoked, the destination must have registered for the pasteboard data type involved in the
drag operation. The messages continue until the image is either released or dragged out of the window or view.
This method provides the destination with an opportunity to modify the dragging operation depending on
the position of the mouse pointer inside of the destination view or window object. For example, you may have
several graphics or areas of text contained within the same view and wish to tailor the dragging operation,
or to ignore the drag event completely, depending upon which object is underneath the mouse pointer at the
time when the user releases the dragged image and the performDragOperation method is invoked.
14.4. CLASS IKIMAGEBROWSERVIEWMBS
381
You typically examine the contents of the pasteboard in the draggingEntered method, where this examination is performed only once, rather than in the draggingUpdated method, which is invoked multiple times.
Only one destination at a time receives a sequence of draggingUpdated messages. If the mouse pointer is
within the bounds of two overlapping views that are both valid destinations, the uppermost view receives
these messages until the image is either released or dragged out.
14.4.82
groupAtIndex(index as Integer) as Dictionary
Plugin Version: 13.1, Console & Web: No, Mac: Yes, Win: No, Linux: No. Function: Returns the group
at the specified index.
Notes:
index: The index of the group you want to retrieve.
Returns a dictionary that defines the group. The keys in this dictionary can be any of the following constants:
IKImageBrowserGroupStyle, IKImageBrowserGroupBackgroundColorKey, IKImageBrowserGroupTitleKey,
and IKImageBrowserGroupRangeKey. For more information on these constants, see IKImageBrowserView
Class Reference.
This method is optional.
Available in OS X v10.5 and later.
14.4.83
itemAtIndex(index as Integer) as IKImageBrowserItemMBS
Plugin Version: 13.1, Console & Web: No, Mac: Yes, Win: No, Linux: No. Function: Returns an object
for the item in an image browser view that corresponds to the specified index.
Notes:
index: The index of the item you want to retrieve.
Return an IKImageBrowserItem object.
Your data source must implement this method. The returned object must implement the required methods
of the IKImageBrowserItem protocol.
Available in OS X v10.5 and later.
382
14.4.84
CHAPTER 14. IMAGEKIT
moveItemsAtIndexes(indexes as NSIndexSetMBS, destinationIndex as
Integer) as boolean
Plugin Version: 13.1, Console & Web: No, Mac: Yes, Win: No, Linux: No. Function: Signals that the
specified items should be moved to the specified destination.
Notes:
indexes: The indexes of the items that should be reordered.
destinationIndex: The starting index of the destination the items should be moved to.
Returns true if successful; false otherwise.
This method is optional. It is invoked by the image browser view after Image Kit determines that a reordering operation should be applied. The data source should update itself by reordering its elements.
Available in OS X v10.5 and later.
14.4.85
numberOfGroups as Integer
Plugin Version: 13.1, Console & Web: No, Mac: Yes, Win: No, Linux: No. Function: Returns the number
of groups in an image browser view.
Notes:
Return the number of groups.
This method is optional.
Available in OS X v10.5 and later.
14.4.86
numberOfItems as Integer
Plugin Version: 13.1, Console & Web: No, Mac: Yes, Win: No, Linux: No. Function: Returns the number
of records managed by the data source object.
Notes:
Return the number of records managed by the image browser view.
Your data source must implement this method. An IKImageView object uses this method to determine how
many cells it should create and display.
Available in OS X v10.5 and later.
14.4. CLASS IKIMAGEBROWSERVIEWMBS
14.4.87
383
performDragOperation(sender as NSDraggingInfoMBS) as boolean
Plugin Version: 13.1, Console & Web: No, Mac: Yes, Win: No, Linux: No. Function: Invoked after the
released image has been removed from the screen, signaling the receiver to import the pasteboard data.
Notes:
sender: The object sending the message; use it to get details about the dragging operation.
Returns if the destination accepts the data, it returns true; otherwise it returns false. The default is to
return false.
For this method to be invoked, the previous prepareForDragOperation message must have returned true.
The destination should implement this method to do the real work of importing the pasteboard data represented by the image.
If the sender object’s animatesToDestination was set to true in prepareForDragOperation, then setup any
animation to arrange space for the drag items to animate to. Also at this time, enumerate through the
dragging items to set their destination frames and destination images.
14.4.88
prepareForDragOperation(sender as NSDraggingInfoMBS) as boolean
Plugin Version: 13.1, Console & Web: No, Mac: Yes, Win: No, Linux: No. Function: Invoked when the
image is released, allowing the receiver to agree to or refuse drag operation.
Notes:
sender: The object sending the message; use it to get details about the dragging operation.
Return true if the receiver agrees to perform the drag operation and false if not.
This method is invoked only if the most recent draggingEntered or draggingUpdated event returned an acceptable drag-operation value.
If you want the drag items to animate from their current location on screen to their final location in your
view, set the sender object’s animatesToDestination property to true in your implementation of this event.
14.4.89
removeItemsAtIndexes(indexes as NSIndexSetMBS)
Plugin Version: 13.1, Console & Web: No, Mac: Yes, Win: No, Linux: No. Function: Signals that a
remove operation should be applied to the specified items.
Notes:
384
CHAPTER 14. IMAGEKIT
indexes: The indexes of the items that should be removed.
This method is optional. It is invoked by the image browser after Image Kit determines that a remove
operation should be applied. In response, the data source should update itself by removing the specified
items.
Available in OS X v10.5 and later.
14.4.90
selectionDidChange
Plugin Version: 13.1, Console & Web: No, Mac: Yes, Win: No, Linux: No. Function: Performs custom
tasks when the selection changes.
Notes:
This method signals that the user changes the selection in the image browser view. You can implement this
method if you want to perform custom tasks at that time.
Available in OS X v10.5 and later.
14.4.91
updateDraggingItemsForDrag(sender as NSDraggingInfoMBS)
Plugin Version: 13.1, Console & Web: No, Mac: Yes, Win: No, Linux: No. Function: Invoked when the
dragging images should be changed.
Notes:
sender: The object sending the message; use this object to get details about the dragging operation.
While a destination may change the dragging images at any time, it is recommended to wait until this
method is called before updating the dragging images.
This allows the system to delay changing the dragging images until it is likely that the user will drop on
this destination. Otherwise, the dragging images will change too often during the drag which would be
distracting to the user.
During enumerateDraggingItemsWithOptions you may set non-acceptable drag items images to nil to hide
them or use the enumeration option of NSDraggingItemEnumerationClearNonenumeratedImages If there
are items that you hide, then after enumeration, you need to set the numberOfValidItemsForDrop to the
number of non-hidden drag items. However, if the valid item count is 0, then it is better to return NSDragOperationNone from your implementation of draggingEntered and, or draggingUpdated instead of hiding all
drag items during enumeration.
Available in OS X v10.7 and later.
14.4. CLASS IKIMAGEBROWSERVIEWMBS
14.4.92
385
wantsPeriodicDraggingUpdates as boolean
Plugin Version: 13.1, Console & Web: No, Mac: Yes, Win: No, Linux: No. Function: Asks the destination
object whether it wants to receive periodic draggingUpdated events.
Notes:
Returns true if the destination wants to receive periodic draggingUpdated messages, false otherwise.
If the destination returns false, these messages are sent only when the mouse moves or a modifier flag changes.
Otherwise the destination gets the default behavior, where it receives periodic dragging-updated events even
if nothing changes.
14.4.93
writeItemsAtIndexes(indexes as NSIndexSetMBS, pasteboard as NSPasteboardMBS) as Integer
Plugin Version: 13.1, Console & Web: No, Mac: Yes, Win: No, Linux: No. Function: Signals that a drag
should begin.
Notes:
itemIndexes: The indexes of the items that should be dragged.
pasteboard: The pasteboard to copy the items to.
Returns the number of items written to the pasteboard.
This method is optional. It is invoked after Image Kit determines that a drag should begin, but before the
drag has been started.
Available in OS X v10.5 and later.
14.4.94
Constants
14.4.95
IKCellsStyleNone = 0
Plugin Version: 13.1. Function: One of the cell style constants.
Notes: No style.
14.4.96
IKCellsStyleOutlined = 2
Plugin Version: 13.1. Function: One of the cell style constants.
Notes: Cells are outlined.
386
14.4.97
CHAPTER 14. IMAGEKIT
IKCellsStyleShadowed = 1
Plugin Version: 13.1. Function: One of the cell style constants.
Notes: Cells use shadows.
14.4.98
IKCellsStyleSubtitled = 8
Plugin Version: 13.1. Function: One of the cell style constants.
Notes: Cells display a subtitle.
14.4.99
IKCellsStyleTitled = 4
Plugin Version: 13.1. Function: One of the cell style constants.
Notes: Cells display a title.
14.4.100
IKGroupBezelStyle = 0
Plugin Version: 13.1. Function: One of the bevel styles.
Notes:
A bezel style.
Available in OS X v10.5 and later.
14.4.101
IKGroupDisclosureStyle = 1
Plugin Version: 13.1. Function: One of the bevel styles.
Notes:
A disclosure triangle.
Available in OS X v10.5 and later.
14.4.102
IKImageBrowserDropBefore = 1
Plugin Version: 13.1. Function: One of the constants to specify the locations for dropping items onto the
browser view.
Notes:
Drop the item before the cell.
Available in OS X v10.6 and later.
14.4. CLASS IKIMAGEBROWSERVIEWMBS
387
Used by the method setDropIndex.
14.4.103
IKImageBrowserDropOn = 0
Plugin Version: 13.1. Function: One of the constants to specify the locations for dropping items onto the
browser view.
Notes:
Drop the item on the cell.
Available in OS X v10.6 and later.
Used by the method setDropIndex.
388
CHAPTER 14. IMAGEKIT
14.5
class IKImageEditPanelMBS
14.5.1
class IKImageEditPanelMBS
Plugin Version: 8.1, Console & Web: No, Mac: Yes, Win: No, Linux: No. Function: The class for the
image edit panel from Mac OS X 10.5.
Notes: Subclass of the NSPanelMBS class.
14.5.2
Methods
14.5.3
Constructor
Plugin Version: 8.4, Console & Web: No, Mac: Yes, Win: No, Linux: No. Function: The constructor to
create a new image edit panel.
14.5.4
reloadData
Plugin Version: 8.1, Console & Web: No, Mac: Yes, Win: No, Linux: No. Function: Requests the panel
to reload the image.
Notes: Do call this if you have a new image to return in the image event.
14.5.5
Properties
14.5.6
LastImage as Picture
Plugin Version: 8.1, Console & Web: No, Mac: Yes, Win: No, Linux: No. Function: The last image passed
to you or requested from you.
Notes:
This property is set with the picture you return with the image event and is set with the image sent to you
useing the Changed event.
(Read and Write property)
14.5. CLASS IKIMAGEEDITPANELMBS
389
14.5.7
Events
14.5.8
Changed(pic as picture, CGImageHandle as Integer, metaData as dictionary)
Plugin Version: 8.1, Console & Web: No, Mac: Yes, Win: No, Linux: No. Function: The image changed
and you should update your GUI.
Notes:
pic: The image as a picture.
CGImageHandle: The internal handle to the original CGImage which is used to make the picture.
metaData: additional image data.
14.5.9
hasAdjustMode as Boolean
Plugin Version: 13.5, Console & Web: No, Mac: Yes, Win: No, Linux: No. Function: Returns whether
the adjust mode view tab should be displayed.
Notes:
Return true if the tab should be displayed, otherwise false.
Available on Mac OS X 10.6 or newer.
14.5.10
hasDetailsMode as Boolean
Plugin Version: 13.5, Console & Web: No, Mac: Yes, Win: No, Linux: No. Function: Returns whether
the details mode view tab should be displayed.
Notes:
True if the tab should be displayed, otherwise false.
Available on Mac OS X 10.6 or newer.
14.5.11
hasEffectsMode as Boolean
Plugin Version: 13.5, Console & Web: No, Mac: Yes, Win: No, Linux: No. Function: Returns whether
the effects mode view tab should be displayed.
Notes:
True if the tab should be displayed, otherwise false.
Available on Mac OS X 10.6 or newer.
390
14.5.12
CHAPTER 14. IMAGEKIT
Image as picture
Plugin Version: 8.1, Console & Web: No, Mac: Yes, Win: No, Linux: No. Function: The panel needs an
image to start with.
Notes: Return your image in this event whenever the panel needs it.
14.5.13
imageProperties as Dictionary
Plugin Version: 13.5, Console & Web: No, Mac: Yes, Win: No, Linux: No. Function: Returns a dictionary
of the image properties associated with the image in the image edit panel.
Notes: Available on Mac OS X 10.5 or newer.
14.5.14
thumbnailWithMaximumSize(Width as Double, Height as Double) as
picture
Plugin Version: 13.5, Console & Web: No, Mac: Yes, Win: No, Linux: No. Function: Returns a thumbnail
image whose size is no larger than the specified size.
Notes: Available in OS X v 10.5 and later.
14.6. CLASS IKPICTURETAKERMBS
14.6
class IKPictureTakerMBS
14.6.1
class IKPictureTakerMBS
391
Plugin Version: 7.7, Console & Web: No, Mac: Yes, Win: No, Linux: No. Function: An IKPictureTaker
object is a panel that allows users to choose and crop an image.
Notes:
It supports browsing of the file system and includes a recents popup-menu. The IKPictureTaker lets the
user to crop a choosen image or to take snapshot from a camera like the built-in iSight.
Requires Mac OS X 10.5.
Subclass of the NSPanelMBS class.
14.6.2
Methods
14.6.3
Available as boolean
Plugin Version: 7.7, Console & Web: No, Mac: Yes, Win: No, Linux: No. Function: Whether the picture
taker is available on that platform or not.
Example:
dim n as Integer
dim p as new IKPictureTakerMBS
if not p.Available then
MsgBox ”This application requires Mac OS X 10.5 and a Macho Target”
Return
end if
Notes: True on Mac OS X 10.5.
14.6.4
beginPictureTaker as boolean
Plugin Version: 7.7, Console & Web: No, Mac: Yes, Win: No, Linux: No. Function: Launch the PictureTaker.
Example:
dim p as IKPictureTakerMBS // your picture taker
392
CHAPTER 14. IMAGEKIT
if not p.beginPictureTaker then
MsgBox ”Can’t show picture taker!?”
end if
Notes:
You will later receive an event for the case the user clicks on OK or Cancel buttons.
Returns true on success and false on failure.
14.6.5
beginPictureTakerSheet(parent as NSWindowMBS) as boolean
Plugin Version: 9.6, Console & Web: No, Mac: Yes, Win: No, Linux: No. Function: Opens a picture taker
as a sheet whose parent is the specified window.
Notes:
parent: The parent window of the picture taker sheet.
You will later receive an event for the case the user clicks on OK or Cancel buttons.
Available in Mac OS X v10.5 and later.
See also:
• 14.6.6 beginPictureTakerSheet(parent as window) as boolean
14.6.6
392
beginPictureTakerSheet(parent as window) as boolean
Plugin Version: 9.6, Console & Web: No, Mac: Yes, Win: No, Linux: No. Function: Opens a picture taker
as a sheet whose parent is the specified window.
Notes:
parent: The parent window of the picture taker sheet.
You will later receive an event for the case the user clicks on OK or Cancel buttons.
Available in Mac OS X v10.5 and later.
See also:
• 14.6.5 beginPictureTakerSheet(parent as NSWindowMBS) as boolean
392
14.6. CLASS IKPICTURETAKERMBS
14.6.7
393
Constructor
Plugin Version: 8.4, Console & Web: No, Mac: Yes, Win: No, Linux: No. Function: The constructor to
create a new picture taker panel.
14.6.8
CropAreaSizeHeight as Double
Plugin Version: 7.7, Console & Web: No, Mac: Yes, Win: No, Linux: No. Function: The height of the
crop area.
14.6.9
CropAreaSizeWidth as Double
Plugin Version: 7.7, Console & Web: No, Mac: Yes, Win: No, Linux: No. Function: The width of the crop
area.
14.6.10
outputImage as NSImageMBS
Plugin Version: 7.7, Console & Web: No, Mac: Yes, Win: No, Linux: No. Function: Return the edited
image.
14.6.11
OutputImageMaxSizeKeyHeight as Double
Plugin Version: 7.7, Console & Web: No, Mac: Yes, Win: No, Linux: No. Function: The maximum height
of the output image.
14.6.12
OutputImageMaxSizeKeyWidth as Double
Plugin Version: 7.7, Console & Web: No, Mac: Yes, Win: No, Linux: No. Function: The maximum width
of the output image.
14.6.13
popUpRecentsMenuForView(parent as NSViewMBS) as boolean
Plugin Version: 9.6, Console & Web: No, Mac: Yes, Win: No, Linux: No. Function: Displays the Open
Recent popup menu associated with the picture taker.
Notes:
394
CHAPTER 14. IMAGEKIT
You will later receive an event for the case the user clicks on OK or Cancel buttons.
Available in Mac OS X v10.5 and later.
14.6.14
runModal as Integer
Plugin Version: 7.7, Console & Web: No, Mac: Yes, Win: No, Linux: No. Function: Launches a modal
PictureTaker session.
Example:
dim p as IKPictureTakerMBS // global property
dim n as Integer
p=new IKPictureTakerMBS
if not p.Available then
MsgBox ”This application requires Mac OS X 10.5 and a Macho Target”
Return
end if
p.AllowsFileChoosing=true
p.AllowsEditing=true
p.AllowsVideoCapture=true
p.ShowEffects=FALSE // disable if you run modal!
p.ShowRecentPicture=true
p.UpdateRecentPicture=true
p.InformationalText=”Please take a picture”
n=p.runModal
if n=1 then // ok
Backdrop=p.outputImage.CopyPictureWithMask
else
Title=Str(n)
end if
Notes:
Returns NSOKButton (1) if the user edits or chooses an image and confirm panel, NSCancelButton (0) if
the user canceled or didn’t change the image.
You may want to disable effects as they won’t work in Realbasic in a modal picture taker dialog.
14.6. CLASS IKPICTURETAKERMBS
14.6.15
395
SetCropAreaSize(width as Double, height as Double)
Plugin Version: 7.7, Console & Web: No, Mac: Yes, Win: No, Linux: No. Function: Sets the crop area.
14.6.16
SetOutputImageMaxSize(width as Double, height as Double)
Plugin Version: 7.7, Console & Web: No, Mac: Yes, Win: No, Linux: No. Function: Sets the maximum
output image size.
14.6.17
Properties
14.6.18
AllowsEditing as boolean
Plugin Version: 7.7, Console & Web: No, Mac: Yes, Win: No, Linux: No. Function: Whether editing is
allowed or not.
Notes: (Read and Write computed property)
14.6.19
AllowsFileChoosing as boolean
Plugin Version: 7.7, Console & Web: No, Mac: Yes, Win: No, Linux: No. Function: Whether choosing a
file is allowed or not.
Notes: (Read and Write computed property)
14.6.20
AllowsVideoCapture as boolean
Plugin Version: 7.7, Console & Web: No, Mac: Yes, Win: No, Linux: No. Function: Whether video
capture is allowed or not.
Notes: (Read and Write computed property)
14.6.21
InformationalText as NSAttributedStringMBS
Plugin Version: 7.7, Console & Web: No, Mac: Yes, Win: No, Linux: No. Function: The information text
as a plain string.
Notes:
On getting the value the plugin will check whether the value is a formatted or a plain text. if it is a plain
text, it will return the plain text as a NSAttributedStringMBS.
396
CHAPTER 14. IMAGEKIT
(Read and Write computed property)
See also:
• 14.6.22 InformationalText as string
14.6.22
396
InformationalText as string
Plugin Version: 7.7, Console & Web: No, Mac: Yes, Win: No, Linux: No. Function: The information text
as a plain string.
Example:
dim p as IKPictureTakerMBS // your picture taker
p.InformationalText=”Please take a picture”
Notes:
On getting the value the plugin will check whether the value is a formatted or a plain text. if it is a formatted
text, it will return the formatted text as plain text.
(Read and Write computed property)
See also:
• 14.6.21 InformationalText as NSAttributedStringMBS
14.6.23
395
inputImage as NSImageMBS
Plugin Version: 7.7, Console & Web: No, Mac: Yes, Win: No, Linux: No. Function: The input image.
Notes:
The input image is never modified by the PictureTaker.
(Read and Write computed property)
14.6.24
mirroring as boolean
Plugin Version: 7.7, Console & Web: No, Mac: Yes, Win: No, Linux: No. Function: True if video mirroring
is enabled, false otherwise.
Notes:
Controls whether the receiver enable/disable video mirroring durring snapshots (default is true).
(Read and Write computed property)
14.6. CLASS IKPICTURETAKERMBS
14.6.25
397
RemainOpenAfterValidate as boolean
Plugin Version: 9.6, Console & Web: No, Mac: Yes, Win: No, Linux: No. Function: Whether the picture
taker reamins open.
Notes:
Requires Mac OS X 10.6.
(Read and Write computed property)
14.6.26
ShowAddressBookPicture as boolean
Plugin Version: 7.7, Console & Web: No, Mac: Yes, Win: No, Linux: No. Function: Whether the addressbook picture is shown or not.
Notes: (Read and Write computed property)
14.6.27
ShowEffects as boolean
Plugin Version: 7.7, Console & Web: No, Mac: Yes, Win: No, Linux: No. Function: Whether effects are
shown or not.
Notes: (Read and Write computed property)
14.6.28
ShowEmptyPicture as NSImageMBS
Plugin Version: 13.5, Console & Web: No, Mac: Yes, Win: No, Linux: No. Function: The image to use
for an empty image.
Notes: (Read and Write computed property)
14.6.29
ShowRecentPicture as boolean
Plugin Version: 7.7, Console & Web: No, Mac: Yes, Win: No, Linux: No. Function: Whether recent
pictures should be shown.
Notes: (Read and Write computed property)
14.6.30
UpdateRecentPicture as boolean
Plugin Version: 7.7, Console & Web: No, Mac: Yes, Win: No, Linux: No. Function: Whether recent
pictures should be updated.
398
CHAPTER 14. IMAGEKIT
Notes: (Read and Write computed property)
14.6.31
Events
14.6.32
Finished(returnCode as Integer)
Plugin Version: 7.7, Console & Web: No, Mac: Yes, Win: No, Linux: No. Function: beginPictureTaker
has finished work.
Notes: ReturnCode is 1 if the user clicked OK and 0 if the user clicked false.
14.7. CLASS IKSLIDESHOWMBS
14.7
class IKSlideshowMBS
14.7.1
class IKSlideshowMBS
399
Plugin Version: 7.7, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: The ImageKit class
for a slideshow.
Notes:
Requires Mac OS X 10.5.
Slideshows can be only with pictures, with PDF pages or with file references.
Those files can be picture files, pdf files or anything you want.
14.7.2
Methods
14.7.3
addFile(file as folderitem, name as string=””)
Plugin Version: 8.6, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: Adds a file to the
items list.
14.7.4
addImage(image as NSImageMBS, name as string=””)
Plugin Version: 8.6, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: Adds an image to
the items list.
Example:
dim p as picture
dim n as NSImageMBS
dim s as new IKSlideshowMBS
// get picture to p
n=new NSImageMBS(p)
s.addImage n
14.7.5
addPage(page as Variant, name as string=””)
Plugin Version: 8.6, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: Adds a PDF page to
the items list.
Notes: Page must be a PDFPageMBS object.
400
14.7.6
CHAPTER 14. IMAGEKIT
autoPlayDelay as Double
Plugin Version: 7.7, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: The time to wait
before the slideshow will start automatically.
Notes:
Value is in seconds.
(Read and Write computed property)
14.7.7
Available as boolean
Plugin Version: 7.7, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: Whether the slide
show functions are available.
Example:
if IKSlideshowMBS.Available=False then
MsgBox ”You need Mac OS X 10.5 for this and a MachO application.”
quit
end if
Notes: Value is true for Mac OS X 10.5.
14.7.8
canExportToApplication(applicationBundleIdentifier as string) as boolean
Plugin Version: 7.7, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: is exporting to a
given application possible?
Notes: (application installed?, right version?, ...)
14.7.9
exportSlideshowItems(applicationBundleIdentifier as string)
Plugin Version: 7.7, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: Export items to the
given application.
Example:
dim i,c as Integer
dim s as new IKSlideshowMBS
// add items here
if false=IKSlideshowMBS.canExportToApplication(IKSlideshowMBS.iPhotoBundleIdentifier) then
MsgBox ”Can’t export to iPhoto.”
14.7. CLASS IKSLIDESHOWMBS
401
else
if s.itemcount>0 then
s.exportSlideshowItems IKSlideshowMBS.iPhotoBundleIdentifier
else
MsgBox ”no slides?”
end if
end if
14.7.10
indexOfCurrentSlideshowItem as Integer
Plugin Version: 7.7, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: The index of the
current slide.
Notes: Index is from 0 to count-1.
14.7.11
ItemCount as Integer
Plugin Version: 8.6, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: Returns the number
of items.
14.7.12
reloadData
Plugin Version: 7.7, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: Reloads all slides.
14.7.13
reloadSlideshowItemAtIndex(index as Integer)
Plugin Version: 7.7, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: Reloads the slide
show with the given index.
14.7.14
removeItem(index as Integer)
Plugin Version: 8.6, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: Removes an item
from the item list.
402
14.7.15
CHAPTER 14. IMAGEKIT
removeItems
Plugin Version: 8.6, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: Removes all items
from the item list.
14.7.16
runSlideshow
Plugin Version: 7.7, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: Start the slideshow.
Example:
dim s as new IKSlideshowMBS
// add items
s.runSlideshow
Notes: You may want to set all the properties before.
14.7.17
setFile(index as Integer, file as folderitem, name as string=””)
Plugin Version: 8.6, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: Sets the file in the
items list with the given index.
14.7.18
setImage(index as Integer, image as NSImageMBS, name as string=””)
Plugin Version: 8.6, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: Sets the image in
the items list with the given index.
14.7.19
setPage(index as Integer, page as Variant, name as string=””)
Plugin Version: 8.6, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: Sets a PDF page in
the items list with the given index.
Notes: Page must be a PDFPageMBS object.
14.7.20
stopSlideshow
Plugin Version: 7.7, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: Stops the slideshow.
14.7. CLASS IKSLIDESHOWMBS
14.7.21
Properties
14.7.22
AudioFile as Folderitem
403
Plugin Version: 9.6, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: Optional audio file
to play while running slide show.
Notes:
Only used for Mac OS X 10.6.
(Read and Write property)
14.7.23
PDFDisplayBox as Integer
Plugin Version: 7.7, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: The PDF display
box mode to use.
Notes:
Default value is -1 which means that we use the framework default mode.
(Read and Write property)
14.7.24
PDFDisplayMode as Integer
Plugin Version: 7.7, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: The PDF display
mode you want.
Notes:
Default value is -1 which means that we use the framework default mode.
(Read and Write property)
14.7.25
PDFDisplaysAsBook as Boolean
Plugin Version: 7.7, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: Whether PDF should
display as book.
Notes:
Default value is false.
(Read and Write property)
404
14.7.26
CHAPTER 14. IMAGEKIT
ScreenIndex as Integer
Plugin Version: 9.6, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: The screen to use.
Notes:
Default is main screen.
Only used for Mac OS X 10.6.
(Read and Write property)
14.7.27
StartIndex as Integer
Plugin Version: 7.7, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: The index of the first
slide to show.
Notes:
Index is from 0 to count-1.
Default value is -1 which means that we use the framework default mode.
(Read and Write property)
14.7.28
StartPaused as Boolean
Plugin Version: 7.7, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: Whether to start
paused.
Notes:
Default is false.
(Read and Write property)
14.7.29
WrapAround as Boolean
Plugin Version: 7.7, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: Whether to wrap
around when the slideshow runs.
Notes:
Default is false.
(Read and Write property)
14.7. CLASS IKSLIDESHOWMBS
405
14.7.30
Events
14.7.31
canExportSlideshowItemAtIndex(index as Integer, applicationBundleIdentifier as string) as boolean
Plugin Version: 7.7, Console & Web: No, Mac: Yes, Win: No, Linux: No. Function: Should the export
button be enabled for a given item at index?
Notes: This event is optional.
14.7.32
slideshowDidChangeCurrentIndex(newIndex as Integer)
Plugin Version: 7.7, Console & Web: No, Mac: Yes, Win: No, Linux: No. Function: Slideshow did change
current item index.
14.7.33
slideshowDidStop
Plugin Version: 7.7, Console & Web: No, Mac: Yes, Win: No, Linux: No. Function: Slideshow did stop
Notes: This event is optional.
14.7.34
slideshowWillStart
Plugin Version: 7.7, Console & Web: No, Mac: Yes, Win: No, Linux: No. Function: Slideshow will start.
Notes: This event is optional.
14.7.35
Constants
14.7.36
iPhotoBundleIdentifier=”com.apple.iPhoto”
Plugin Version: 7.7. Function: The iPhoto application identifier.
Notes: May be used on the export functions.
14.7.37
kPDFDisplayBoxArtBox=4
Plugin Version: 7.7. Function: One of the possible values for the PDFDisplayBox property.
406
14.7.38
CHAPTER 14. IMAGEKIT
kPDFDisplayBoxBleedBox=2
Plugin Version: 7.7. Function: One of the possible values for the PDFDisplayBox property.
14.7.39
kPDFDisplayBoxCropBox=1
Plugin Version: 7.7. Function: One of the possible values for the PDFDisplayBox property.
14.7.40
kPDFDisplayBoxMediaBox=0
Plugin Version: 7.7. Function: One of the possible values for the PDFDisplayBox property.
14.7.41
kPDFDisplayBoxTrimBox=3
Plugin Version: 7.7. Function: One of the possible values for the PDFDisplayBox property.
14.7.42
kPDFDisplaySinglePage=0
Plugin Version: 7.7. Function: One of the PDF display mode constants.
14.7.43
kPDFDisplaySinglePageContinuous=1
Plugin Version: 7.7. Function: One of the PDF display mode constants.
14.7.44
kPDFDisplayTwoUp=2
Plugin Version: 7.7. Function: One of the PDF display mode constants.
14.7.45
kPDFDisplayTwoUpContinuous=3
Plugin Version: 7.7. Function: One of the PDF display mode constants.
Chapter 15
JavaScript
15.1
class JSClassMBS
15.1.1
class JSClassMBS
Plugin Version: 15.4, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: The class for a class
in javascript.
Notes: This is an abstract class. You can’t create an instance, but you can get one from various plugin
functions.
15.1.2
Methods
15.1.3
Constructor
Plugin Version: 15.4, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: The private constructor.
15.1.4
NewObject as JSObjectMBS
Plugin Version: 15.4, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: Creates a JavaScript
object for current class.
407
408
CHAPTER 15. JAVASCRIPT
15.1.5
Properties
15.1.6
context as JSContextMBS
Plugin Version: 15.4, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: The context for this
class.
Notes: (Read only property)
15.1.7
Handle as Integer
Plugin Version: 15.4, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: The handle for the
class object.
Notes: (Read and Write property)
15.1.8
Tag as Variant
Plugin Version: 15.4, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: The tag value.
Notes:
You can store anything here and as long as the JSClass object exists, this value is kept referenced.
(Read and Write property)
15.2. CLASS JSCONTEXTMBS
15.2
class JSContextMBS
15.2.1
class JSContextMBS
409
Plugin Version: 15.4, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: The class for a
javascript execution context.
Example:
dim c as new JSContextMBS
dim e as JSValueMBS
dim v as JSValueMBS = c.EvaluateScript(”1+2”, ””, nil, e)
if e <>nil then
// show error
MsgBox e.StringValue
else
// show result
MsgBox str(v.doubleValue)
end if
15.2.2
Methods
15.2.3
CheckScriptSyntax(script as string, sourceURL as String, startingLineNumber as Integer = 1, byref JSException as JSValueMBS) as Boolean
Plugin Version: 15.4, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: Checks for syntax
errors in a string of JavaScript.
Example:
dim c as new JSContextMBS
dim e as JSValueMBS
if c.CheckScriptSyntax(”1+”, ””, e) then
MsgBox ”OK”
else
// show error
MsgBox e.StringValue
end if
Notes:
Script: A string containing the script to check for syntax errors.
sourceURL: A string containing a URL for the script’s source file. This is only used when reporting excep-
410
CHAPTER 15. JAVASCRIPT
tions. Pass ”” if you do not care to include source file information in exceptions.
startingLineNumber: An integer value specifying the script’s starting line number in the file located at
sourceURL. This is only used when reporting exceptions. The value is one-based, so the first line is line 1
and invalid values are clamped to 1.
exception: A JSValue in which to store a syntax error exception, if any.
Returns true if the script is syntactically correct, otherwise false.
15.2.4
Constructor
Plugin Version: 15.4, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: The constructor.
Notes: Creates a global JavaScript execution context.
15.2.5
EvaluateScript(script as string, sourceURL as String, thisObject as JSValueMBS, startingLineNumber as Integer = 1, byref JSException as
JSValueMBS) as JSValueMBS
Plugin Version: 15.4, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: Evaluates a string
of JavaScript.
Example:
dim c as new JSContextMBS
dim e as JSValueMBS
dim v as JSValueMBS = c.EvaluateScript(”1+”, ””, nil, e)
if e <>nil then
// show error
MsgBox e.StringValue
else
// show result
MsgBox str(v.doubleValue)
end if
Notes:
script: A string containing the script to evaluate.
thisObject: The object to use as ”this,” or nil to use the global object as ”this.”
sourceURL: A string containing a URL for the script’s source file. This is used by debuggers and when
reporting exceptions. Pass ”” if you do not care to include source file information.
startingLineNumber: An integer value specifying the script’s starting line number in the file located at
sourceURL. This is only used when reporting exceptions. The value is one-based, so the first line is line 1
and invalid values are clamped to 1.
15.2. CLASS JSCONTEXTMBS
411
exception: A JSValueMBS in which to store an exception, if any.
Returns the JSValue that results from evaluating script, or nil if an exception is thrown.
15.2.6
GarbageCollect
Plugin Version: 15.4, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: Performs a
JavaScript garbage collection.
Notes:
JavaScript values that are on the machine stack, in a register, protected by JSValueProtect, set as the global
object of an execution context, or reachable from any such value will not be collected.
During JavaScript execution, you are not required to call this function; the JavaScript engine will garbage
collect as needed. JavaScript values created within a context group are automatically destroyed when the
last reference to the context group is released.
15.2.7
NewArray(arguments() as JSValueMBS, byref JSException as JSValueMBS) as JSObjectMBS
Plugin Version: 15.4, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: Creates a JavaScript
Array object.
Example:
dim c as new JSContextMBS
dim e as JSValueMBS
dim v as JSObjectMBS = c.NewArray(nil, e)
v.SetPropertyAtIndex(0, c.valueWithString(”Hello”), e)
v.SetPropertyAtIndex(1, c.valueWithString(”World”), e)
MsgBox v.JSONString
Notes:
arguments: A JSValue array of data to populate the Array with.
JSException: A JSValueMBS in which to store an exception, if any.
Returns a JSObject that is an Array.
The behavior of this function does not exactly match the behavior of the built-in Array constructor. Specifically, if one argument is supplied, this function returns an array with one element.
Requires Mac OS X 10.6 or newer.
412
15.2.8
CHAPTER 15. JAVASCRIPT
NewDate(arguments() as JSValueMBS, byref JSException as JSValueMBS) as JSObjectMBS
Plugin Version: 15.4, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: Creates a JavaScript
Date object, as if by invoking the built-in Date constructor.
Example:
dim c as new JSContextMBS
dim year as JSValueMBS = c.valueWithDouble(2015)
dim month as JSValueMBS = c.valueWithDouble(5)
dim day as JSValueMBS = c.valueWithDouble(12)
dim e as JSValueMBS // exception
dim d as JSValueMBS = c.NewDate(array(year, month, day), e)
MsgBox d.JSONString
Notes:
arguments: A JSValue array of arguments to pass to the Date Constructor.
JSException: A JSValueMBS in which to store an exception, if any.
Returns a JSObject that is a Date.
Requires Mac OS X 10.6 or newer.
15.2.9
NewError(arguments() as JSValueMBS, byref JSException as JSValueMBS) as JSObjectMBS
Plugin Version: 15.4, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: Creates a JavaScript
Error object, as if by invoking the built-in Error constructor.
Example:
dim c as new JSContextMBS
dim parameters() as JSValueMBS
Parameters.Append c.valueWithString(”Hello”)
dim ex as JSValueMBS
dim e as JSValueMBS = c.NewError(Parameters, ex)
MsgBox e.StringValue
Notes:
arguments: A JSValue array of arguments to pass to the Error Constructor.
15.2. CLASS JSCONTEXTMBS
413
JSException: A JSValueMBS in which to store an exception, if any.
Returns a JSObject that is a Error.
Requires Mac OS X 10.6 or newer.
15.2.10
NewFunction(name as string) as JSObjectMBS
Plugin Version: 15.4, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: Convenience method
for creating a JavaScript function which raises FunctionCalled event on invokation.
Notes:
name: A string containing the function’s name. This will be used when converting the function to string.
Pass NULL to create an anonymous function.
Returns a JSObject that is a function. The object’s prototype will be the default function prototype.
See also:
• 15.2.11 NewFunction(name as string, parameterNames() as string, Body as String, SourceURL as
string = ””, startingLineNumber as Integer = 0, byref JSException as JSValueMBS) as JSValueMBS
413
15.2.11
NewFunction(name as string, parameterNames() as string, Body as
String, SourceURL as string = ””, startingLineNumber as Integer =
0, byref JSException as JSValueMBS) as JSValueMBS
Plugin Version: 15.4, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: Creates a function
with a given script as its body.
Example:
dim c as new JSContextMBS
// create a function
dim parameterNames() as string = array(”value”)
dim body as string = ”return value*value;”
dim name as string = ”test”
dim e as JSValueMBS
dim v as JSValueMBS = c.NewFunction(name, parameterNames, body, e )
MsgBox v.StringValue
// put it in global memory
c.globalObject.SetProperty ”test”, v, e
// and call it
dim r as JSValueMBS = c.EvaluateScript(”test(5)”, ””, nil, e)
414
CHAPTER 15. JAVASCRIPT
MsgBox r.StringValue
Notes:
name: A string containing the function’s name. This will be used when converting the function to string.
Pass ”” to create an anonymous function.
parameterNames: A string array containing the names of the function’s parameters.
body: A string containing the script to use as the function’s body.
sourceURL: A string containing a URL for the script’s source file. This is only used when reporting exceptions. Pass ”” if you do not care to include source file information in exceptions.
startingLineNumber: An integer value specifying the script’s starting line number in the file located at
sourceURL. This is only used when reporting exceptions. The value is one-based, so the first line is line 1
and invalid values are clamped to 1.
exception: A JSValueMBS in which to store a syntax error exception, if any. Pass nil if you do not care to
store a syntax error exception.
A JSObject that is a function, or nil if either body or parameterNames contains a syntax error. The object’s
prototype will be the default function prototype.
Use this method when you want to execute a script repeatedly, to avoid the cost of re-parsing the script
before each execution.
See also:
• 15.2.10 NewFunction(name as string) as JSObjectMBS
15.2.12
413
NewObject as JSObjectMBS
Plugin Version: 15.4, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: Creates a new object.
15.2.13
NewRegExp(arguments() as JSValueMBS, byref JSException as JSValueMBS) as JSObjectMBS
Plugin Version: 15.4, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: Creates a JavaScript
RegExp object, as if by invoking the built-in RegExp constructor.
Notes:
arguments: A JSValue array of arguments to pass to the RegExp Constructor.
JSException: A JSValueMBS in which to store an exception, if any.
Returns a JSObject that is a RegExp.
Requires Mac OS X 10.6 or newer.
15.2. CLASS JSCONTEXTMBS
15.2.14
415
valueWithBool(value as boolean) as JSValueMBS
Plugin Version: 15.4, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: Creates a JavaScript
value of the boolean type.
Example:
dim c as new JSContextMBS
dim v as JSValueMBS = c.valueWithBool(true)
MsgBox v.JSONString
15.2.15
valueWithDouble(value as Double) as JSValueMBS
Plugin Version: 15.4, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: Creates a JavaScript
value of the number type.
Example:
dim c as new JSContextMBS
dim v as JSValueMBS = c.valueWithDouble(5.6)
MsgBox v.StringValue
15.2.16
valueWithJSON(JSON as string) as JSValueMBS
Plugin Version: 15.4, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: Creates a JavaScript
value from a JSON formatted string.
Example:
dim c as new JSContextMBS
dim v as JSValueMBS = c.valueWithJSON(” [ 1,2,3 ] ”)
dim o as JSObjectMBS = JSObjectMBS(v) // arrays are objects
dim e as JSValueMBS
dim p as JSValueMBS = o.GetProperty(”length”, e)
MsgBox p.StringValue // shows 3
Notes:
Returns a JSValue containing the parsed value, or nil if the input is invalid.
Available on Mac OS X 10.7 and newer
416
15.2.17
CHAPTER 15. JAVASCRIPT
valueWithNull as JSValueMBS
Plugin Version: 15.4, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: Creates a JavaScript
value of the null type.
Example:
dim c as new JSContextMBS
dim j as JSValueMBS = c.valueWithNull
if j.Type = JSValueMBS.kJSTypeNull then
MsgBox ”null”
end if
15.2.18
valueWithString(value as string) as JSValueMBS
Plugin Version: 15.4, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: Creates a JavaScript
value of the string type.
Example:
dim c as new JSContextMBS
dim v as JSValueMBS = c.valueWithString(”Hello”)
MsgBox v.StringValue
15.2.19
valueWithUndefined as JSValueMBS
Plugin Version: 15.4, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: Creates a JavaScript
value of the undefined type.
Example:
dim c as new JSContextMBS
dim j as JSValueMBS = c.valueWithUndefined
if j.Type = JSValueMBS.kJSTypeUndefined then
MsgBox ”undefined”
end if
15.2. CLASS JSCONTEXTMBS
15.2.20
Properties
15.2.21
globalObject as JSObjectMBS
417
Plugin Version: 15.4, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: Gets the global
object of a JavaScript execution context.
Example:
dim c as new JSContextMBS
dim v as JSObjectMBS = c.globalObject
dim e as JSValueMBS
v.SetProperty ”Hello”, c.valueWithString(”World”), e
v.SetProperty ”Value”, c.valueWithDouble(5), e
MsgBox c.globalObject.JSONString
Notes: (Read only property)
15.2.22
Handle as Integer
Plugin Version: 15.4, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: The internal object
reference.
Notes: (Read and Write property)
15.2.23
Name as String
Plugin Version: 15.4, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: The name.
Example:
dim c as new JSContextMBS
c.Name = ”Hello”
MsgBox c.Name
Notes:
Requires Mac OS X 10.10 and newer.
(Read and Write property)
418
15.2.24
CHAPTER 15. JAVASCRIPT
Tag as Variant
Plugin Version: 15.4, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: The tag value.
Notes:
You can store anything here and as long as the JSContext object exists, this value is kept referenced.
(Read and Write property)
15.2.25
Events
15.2.26
FunctionCalled(functionObject as JSObjectMBS, thisObject as JSObjectMBS, arguments() as JSValueMBS, byref JSException as JSValueMBS) as JSValueMBS
Plugin Version: 15.4, Console & Web: No, Mac: Yes, Win: No, Linux: No. Function: The event called
when your custom function is called.
Notes: Please return a value and in case of error set exception.
15.3. CLASS JSOBJECTMBS
15.3
class JSObjectMBS
15.3.1
class JSObjectMBS
419
Plugin Version: 15.4, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: The class for a
Javascript Object.
Notes:
Subclass of the JSValueMBS class.
This is an abstract class. You can’t create an instance, but you can get one from various plugin functions.
15.3.2
Methods
15.3.3
CallAsConstructor(arguments() as JSValueMBS, byref JSException as
JSValueMBS) as JSValueMBS
Plugin Version: 15.4, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: Calls an object as
a constructor.
Notes:
self: The JSObject to call as a constructor.
arguments: A JSValueMBS array of arguments to pass to the constructor.
JSException A pointer to a JSValueMBS in which to store an exception, if any.
Returns the JSObject that results from calling object as a constructor, or nil if an exception is thrown or
object is not a constructor.
15.3.4
CallAsFunction(thisObject as JSValueMBS, arguments() as JSValueMBS,
byref JSException as JSValueMBS) as JSValueMBS
Plugin Version: 15.4, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: Calls an object as
a function.
Notes:
self: The JSObject to call as a function.
thisObject: The object to use as ”this,” or nil to use the global object as ”this.”
arguments: A JSValueMBS array of arguments to pass to the function.
JSException: A JSValueMBS in which to store an exception, if any.
Returns the JSValue that results from calling object as a function, or nil if an exception is thrown or object
is not a function.
420
15.3.5
CHAPTER 15. JAVASCRIPT
Constructor
Plugin Version: 15.4, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: The private constructor.
15.3.6
DeleteProperty(name as string, byref JSException as JSValueMBS) as
boolean
Plugin Version: 15.4, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: Deletes a property
from an object.
Example:
dim c as new JSContextMBS
dim v as JSObjectMBS = c.globalObject
dim e as JSValueMBS
v.SetProperty ”Hello”, c.valueWithString(”World”), e
v.SetProperty ”Value”, c.valueWithDouble(5), e
MsgBox v.JSONString
call v.DeleteProperty ”Hello”, e
MsgBox v.JSONString
Notes:
Name: A string containing the property’s name.
JSException: A JSValueMBS in which to store an exception, if any.
Returns true if the delete operation succeeds, otherwise false (for example, if the property has the kJSPropertyAttributeDontDelete attribute set).
15.3.7
GetProperty(name as string, byref JSException as JSValueMBS) as JSValueMBS
Plugin Version: 15.4, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: Gets a property
from an object.
Example:
dim c as new JSContextMBS
dim v as JSObjectMBS = c.globalObject
15.3. CLASS JSOBJECTMBS
421
dim e as JSValueMBS
v.SetProperty ”Hello”, c.valueWithString(”World”), e
MsgBox v.GetProperty(”Hello”, e).StringValue
Notes:
object: The JSObject whose property you want to get.
Name: A string containing the property’s name.
JSException: A JSValueMBS in which to store an exception, if any.
Returns the property’s value if object has the property, otherwise the undefined value.
15.3.8
GetPropertyAtIndex(propertyIndex as Integer, byref JSException as
JSValueMBS) as JSValueMBS
Plugin Version: 15.4, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: Gets a property
from an object by numeric index.
Example:
dim c as new JSContextMBS
dim v as JSValueMBS = c.valueWithJSON(” [ 1,2,3 ] ”)
dim o as JSObjectMBS = JSObjectMBS(v) // arrays are objects
dim e as JSValueMBS
dim p as JSValueMBS = o.GetProperty(”length”, e)
MsgBox ”Length: ”+p.StringValue
dim n as JSValueMBS = o.GetPropertyAtIndex(2, e)
MsgBox ”3rd value in array: ”+n.StringValue
Notes:
The JSObject whose property you want to get.
propertyIndex: An integer value that is the property’s name.
JSException: A JSValueMBS in which to store an exception, if any.
Returns the property’s value if object has the property, otherwise the undefined value.
Calling GetPropertyAtIndex is equivalent to calling GetProperty with a string containing propertyIndex,
422
CHAPTER 15. JAVASCRIPT
but GetPropertyAtIndex provides optimized access to numeric properties.
15.3.9
HasProperty(name as string) as boolean
Plugin Version: 15.4, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: Tests whether an
object has a given property.
Example:
dim c as new JSContextMBS
dim e as JSValueMBS
dim v as JSObjectMBS = c.NewArray(nil, e)
MsgBox str(v.HasProperty(”length”))
Notes:
name: A string containing the property’s name.
Returns true if the object has a property whose name matches propertyName, otherwise false.
15.3.10
PropertyNames as String()
Plugin Version: 15.4, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: Gets the names of
an object’s enumerable properties.
Example:
dim c as new JSContextMBS
dim v as JSObjectMBS = c.globalObject
dim e as JSValueMBS
v.SetProperty ”Hello”, c.valueWithString(”World”), e
v.SetProperty ”Value”, c.valueWithDouble(5), e
MsgBox Join(v.PropertyNames, EndOfLine)
15.3.11
SetProperty(name as string, value as JSValueMBS, byref JSException
as JSValueMBS)
Plugin Version: 15.4, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: Sets a property on
an object.
15.3. CLASS JSOBJECTMBS
423
Example:
dim c as new JSContextMBS
dim v as JSObjectMBS = c.globalObject
dim e as JSValueMBS
v.SetProperty ”Hello”, c.valueWithString(”World”), e
v.SetProperty ”Value”, c.valueWithDouble(5), e
Notes:
Name: A string containing the property’s name.
Value: A JSValue to use as the property’s value.
JSException A pointer to a JSValueRef in which to store an exception, if any.
15.3.12
SetPropertyAtIndex(propertyIndex as Integer, value as JSValueMBS,
byref JSException as JSValueMBS)
Plugin Version: 15.4, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: Sets a property on
an object by numeric index.
Notes:
propertyIndex: The property’s name as a number.
value: A JSValue to use as the property’s value.
exception: A JSValueMBS in which to store an exception, if any.
Calling SetPropertyAtIndex is equivalent to calling SetProperty with a string containing propertyIndex, but
SetPropertyAtIndex provides optimized access to numeric properties.
15.3.13
Properties
15.3.14
isConstructor as Boolean
Plugin Version: 15.4, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: Tests whether an
object can be called as a constructor.
Notes:
Returns true if the object can be called as a constructor, otherwise false.
(Read only property)
424
15.3.15
CHAPTER 15. JAVASCRIPT
isFunction as Boolean
Plugin Version: 15.4, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: Tests whether an
object can be called as a function.
Example:
dim c as new JSContextMBS
dim f as JSObjectMBS = c.NewFunction(”Hello”)
MsgBox str(f.isFunction)
Notes:
Returns true if the object can be called as a function, otherwise false.
(Read only property)
15.3.16
Prototype as JSValueMBS
Plugin Version: 15.4, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: An object’s
prototype.
Example:
dim c as new JSContextMBS
dim j as JSValueMBS = c.valueWithJSON(” { ””tag””: 1 } ”)
dim o as JSObjectMBS = JSObjectMBS(j)
MsgBox ”object prototyp: ”+o.Prototype.StringValue
Notes: (Read and Write property)
15.4. CLASS JSVALUEMBS
15.4
class JSValueMBS
15.4.1
class JSValueMBS
425
Plugin Version: 15.4, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: The class for a
Javascript value.
Example:
dim c as new JSContextMBS
dim j as JSValueMBS = c.valueWithDouble(1)
MsgBox j.StringValue
Notes: This is an abstract class. You can’t create an instance, but you can get one from various plugin
functions.
15.4.2
Methods
15.4.3
Constructor
Plugin Version: 15.4, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: The private constructor.
15.4.4
DoubleValue(byref JSException as JSValueMBS) as Double
Plugin Version: 15.4, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: Converts a
JavaScript value to number and returns the resulting number.
Notes: Returns the numeric result of conversion, or NaN if an exception is thrown.
See also:
• 15.4.15 doubleValue as Double
15.4.5
428
IsEqual(OtherValue as JSValueMBS, byref JSException as JSValueMBS)
as boolean
Plugin Version: 15.4, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: Tests whether two
JavaScript values are equal, as compared by the JS == operator.
Example:
dim c as new JSContextMBS
dim s1 as JSValueMBS = c.valueWithJSON(”””Hello”””)
dim s2 as JSValueMBS = c.valueWithJSON(”””Hello”””)
426
CHAPTER 15. JAVASCRIPT
dim e as JSValueMBS
MsgBox str(s1.IsEqual(s2, e))
Notes:
OtherValue The second value to test.
exception: A JSValueMBS in which to store an exception, if any.
Returns true if the two values are equal, false if they are not equal or an exception is thrown.
15.4.6
IsInstanceOfConstructor(ConstructorFunction as JSObjectMBS, byref
JSException as JSValueMBS) as boolean
Plugin Version: 15.4, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: Tests whether a
JavaScript value is an object constructed by a given constructor, as compared by the JS instanceof operator.
Notes:
ConstructorFunction: The constructor to test against.
JSException: A JSValueMBS in which to store an exception, if any.
Returns true if value is an object constructed by constructor, as compared by the JS instanceof operator,
otherwise false.
15.4.7
IsObjectOfClass(ClassObject as JSValueMBS) as boolean
Plugin Version: 15.4, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: Tests whether a
JavaScript value is an object with a given class in its class chain.
Notes:
ClassObject The JSClass to test against.
Returns true if value is an object and has jsClass in its class chain, otherwise false.
15.4.8
IsStrictEqual(OtherValue as JSValueMBS) as boolean
Plugin Version: 15.4, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: Tests whether two
JavaScript values are strict equal, as compared by the JS === operator.
Example:
dim c as new JSContextMBS
dim j1 as JSValueMBS = c.valueWithDouble(1)
dim j2 as JSValueMBS = c.valueWithDouble(2)
MsgBox str(j1.IsStrictEqual(j2)) // false
MsgBox str(j1.IsStrictEqual(j1)) // true
15.4. CLASS JSVALUEMBS
427
Notes:
OtherValue: The second value to test.
Returns true if the two values are strict equal, otherwise false.
15.4.9
JSONString(indent as Integer = 0, byref JSException as JSValueMBS)
as string
Plugin Version: 15.4, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: Creates a JavaScript
string containing the JSON serialized representation of a JS value.
Example:
dim c as new JSContextMBS
dim j as JSValueMBS = c.valueWithJSON(” { ””tag””:””Hello””, ””value””:1 } ”)
dim e as JSValueMBS
MsgBox j.JSONString(5, e)
Notes:
Requires Mac OS X 10.7 and newer.
The number of spaces to indent when nesting. If 0, the resulting JSON will not contains newlines. The size
of the indent is clamped to 10 spaces.
JSException: A JSValueMBS in which to store an exception, if any.
Returns a JSString with the result of serialization, or nil if an exception is thrown.
See also:
• 15.4.25 JSONString as string
15.4.10
432
ObjectValue(byref JSException as JSValueMBS) as JSValueMBS
Plugin Version: 15.4, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: Converts a
JavaScript value to object and returns the resulting object.
Notes:
JSException: A JSValueMBS in which to store an exception, if any.
Returns the JSObject result of conversion, or nil if an exception is thrown.
428
15.4.11
CHAPTER 15. JAVASCRIPT
StringValue(byref JSException as JSValueMBS) as string
Plugin Version: 15.4, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: Converts a
JavaScript value to string and copies the result into a JavaScript string.
Notes:
JSException: A JSValueMBS in which to store an exception, if any.
Returns a JSString with the result of conversion, or nil if an exception is thrown.
See also:
• 15.4.26 StringValue as String
15.4.12
Properties
15.4.13
booleanValue as Boolean
433
Plugin Version: 15.4, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: Converts a
JavaScript value to boolean and returns the resulting boolean.
Example:
dim c as new JSContextMBS
dim j as JSValueMBS = c.valueWithBool(true)
MsgBox str(j.booleanValue)
Notes: (Read only property)
15.4.14
context as JSContextMBS
Plugin Version: 15.4, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: The context for this
value.
Notes: (Read only property)
15.4.15
doubleValue as Double
Plugin Version: 15.4, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: Converts a
JavaScript value to number and returns the resulting number.
Example:
dim c as new JSContextMBS
dim j as JSValueMBS = c.valueWithDouble(5.3)
MsgBox str(j.doubleValue)
15.4. CLASS JSVALUEMBS
429
Notes:
Returns the numeric result of conversion, or NaN if an exception is thrown.
(Read only property)
See also:
• 15.4.4 DoubleValue(byref JSException as JSValueMBS) as Double
15.4.16
425
Handle as Integer
Plugin Version: 15.4, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: The internal object
reference.
Notes: (Read and Write property)
15.4.17
isArray as Boolean
Plugin Version: 15.4, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: Tests whether a
JavaScript value is an array.
Example:
dim c as new JSContextMBS
dim e as JSValueMBS
dim v as JSValueMBS = c.NewArray(nil, e)
MsgBox str(v.isArray)
Notes:
Returns true if value is an array, otherwise false.
Requires OS X 10.11 or newer.
(Read only property)
15.4.18
isBoolean as Boolean
Plugin Version: 15.4, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: Tests whether a
JavaScript value’s type is the boolean type.
Example:
430
CHAPTER 15. JAVASCRIPT
dim c as new JSContextMBS
dim j as JSValueMBS = c.valueWithBool(true)
MsgBox str(j.isBoolean)
Notes:
Returns true if value’s type is the boolean type, otherwise false.
(Read only property)
15.4.19
isDate as Boolean
Plugin Version: 15.4, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: Tests whether a
JavaScript value is a date.
Example:
dim c as new JSContextMBS
dim year as JSValueMBS = c.valueWithDouble(2015)
dim month as JSValueMBS = c.valueWithDouble(5)
dim day as JSValueMBS = c.valueWithDouble(12)
dim e as JSValueMBS // exception
dim d as JSValueMBS = c.NewDate(array(year, month, day), e)
MsgBox str(d.isDate)
Notes:
Returns true if value is a date, otherwise false.
Requires OS X 10.11 or newer.
(Read only property)
15.4.20
isNull as Boolean
Plugin Version: 15.4, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: Tests whether a
JavaScript value’s type is the null type.
Example:
dim c as new JSContextMBS
dim n as JSValueMBS = c.valueWithNull
MsgBox str(n.isNull)
15.4. CLASS JSVALUEMBS
431
Notes:
Returns true if value’s type is the null type, otherwise false.
(Read only property)
15.4.21
isNumber as Boolean
Plugin Version: 15.4, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: Tests whether a
JavaScript value’s type is the number type.
Example:
dim c as new JSContextMBS
dim j as JSValueMBS = c.valueWithDouble(5)
MsgBox str(j.isNumber)
Notes:
Returns true if value’s type is the number type, otherwise false.
(Read only property)
15.4.22
isObject as Boolean
Plugin Version: 15.4, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: Tests whether a
JavaScript value’s type is the object type.
Example:
dim c as new JSContextMBS
dim e as JSValueMBS
dim v as JSValueMBS = c.NewArray(nil, e)
MsgBox str(v.isObject)
Notes:
Returns true if value’s type is the object type, otherwise false.
(Read only property)
432
15.4.23
CHAPTER 15. JAVASCRIPT
isString as Boolean
Plugin Version: 15.4, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: Tests whether a
JavaScript value’s type is the string type.
Example:
dim c as new JSContextMBS
dim s as JSValueMBS = c.valueWithJSON(”””Hello”””)
MsgBox str(s.isString)
Notes:
Returns true if value’s type is the string type, otherwise false.
(Read only property)
15.4.24
isUndefined as Boolean
Plugin Version: 15.4, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: Tests whether a
JavaScript value’s type is the undefined type.
Example:
dim c as new JSContextMBS
dim j as JSValueMBS = c.valueWithUndefined
MsgBox str(j.isUndefined)
Notes:
Returns true if value’s type is the undefined type, otherwise false.
(Read only property)
15.4.25
JSONString as string
Plugin Version: 15.4, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: Creates a JavaScript
string containing the JSON serialized representation of a JS value.
Example:
dim c as new JSContextMBS
dim v as JSValueMBS = c.valueWithString(”Hello”)
MsgBox v.JSONString
15.4. CLASS JSVALUEMBS
433
Notes:
Requires Mac OS X 10.7 and newer.
(Read only property)
See also:
• 15.4.9 JSONString(indent as Integer = 0, byref JSException as JSValueMBS) as string
15.4.26
427
StringValue as String
Plugin Version: 15.4, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: Converts a
JavaScript value to string and copies the result into a JavaScript string.
Example:
dim c as new JSContextMBS
dim v as JSValueMBS = c.valueWithString(”Hello”)
MsgBox v.StringValue
Notes:
Returns a JSString with the result of conversion, or NULL if an exception is thrown.
(Read only property)
See also:
• 15.4.11 StringValue(byref JSException as JSValueMBS) as string
15.4.27
428
Tag as Variant
Plugin Version: 15.4, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: The tag value.
Notes:
You can store anything here and as long as the JSValue object exists, this value is kept referenced.
(Read and Write property)
15.4.28
Type as Integer
Plugin Version: 15.4, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: Returns a JavaScript
value’s type.
Example:
dim c as new JSContextMBS
dim j as JSValueMBS
434
CHAPTER 15. JAVASCRIPT
j = c.valueWithDouble(1) // double
’j = c.valueWithNull // null
’j = c.valueWithUndefined // undefined
’j = c.valueWithString(”Hello”) // string
’j = c.valueWithJSON(” { ””tag””: 1 } ”) // object
’j = c.valueWithBool(true)
Select case j.Type
case JSValueMBS.kJSTypeUndefined
MsgBox ”undefined”
case JSValueMBS.kJSTypeNull
MsgBox ”null”
case JSValueMBS.kJSTypeBoolean
MsgBox ”boolean ”+str(j.booleanValue)
case JSValueMBS.kJSTypeNumber
MsgBox ”number ”+str(j.doubleValue)
case JSValueMBS.kJSTypeString
MsgBox ”string ”+j.StringValue
case JSValueMBS.kJSTypeObject
MsgBox ”object ”+j.JSONString
else
Break
end Select
Notes: (Read only property)
15.4.29
Constants
15.4.30
kJSTypeBoolean = 2
Plugin Version: 15.4. Function: One of the type constant identifying the type of a JSValue.
Example:
dim c as new JSContextMBS
dim j as JSValueMBS = c.valueWithBool(true)
if j.Type = JSValueMBS.kJSTypeBoolean then
MsgBox ”boolean ”+str(j.booleanValue)
end if
Notes: A primitive boolean value, one of true or false.
15.4. CLASS JSVALUEMBS
15.4.31
kJSTypeNull = 1
Plugin Version: 15.4. Function: One of the type constant identifying the type of a JSValue.
Example:
dim c as new JSContextMBS
dim j as JSValueMBS = c.valueWithNull
if j.Type = JSValueMBS.kJSTypeNull then
MsgBox ”null”
end if
Notes: The unique null value.
15.4.32
kJSTypeNumber = 3
Plugin Version: 15.4. Function: One of the type constant identifying the type of a JSValue.
Example:
dim c as new JSContextMBS
dim j as JSValueMBS = c.valueWithDouble(1) // double
if j.Type = JSValueMBS.kJSTypeNumber then
MsgBox ”number ”+str(j.doubleValue)
end if
Notes: A primitive number value.
15.4.33
kJSTypeObject = 5
Plugin Version: 15.4. Function: One of the type constant identifying the type of a JSValue.
Example:
dim c as new JSContextMBS
dim j as JSValueMBS = c.valueWithJSON(” { ””tag””: 1 } ”)
if j.Type = JSValueMBS.kJSTypeBoolean then
MsgBox ”object ”+j.JSONString
end if
435
436
CHAPTER 15. JAVASCRIPT
Notes: An object value (meaning that this JSValueMBS is a JSObjectMBS).
15.4.34
kJSTypeString = 4
Plugin Version: 15.4. Function: One of the type constant identifying the type of a JSValue.
Example:
dim c as new JSContextMBS
dim j as JSValueMBS = c.valueWithString(”Hello”)
if j.Type = JSValueMBS.kJSTypeString then
MsgBox ”string ”+j.StringValue
end if
Notes: A primitive string value.
15.4.35
kJSTypeUndefined = 0
Plugin Version: 15.4. Function: One of the type constant identifying the type of a JSValue.
Example:
dim c as new JSContextMBS
dim j as JSValueMBS = c.valueWithUndefined
if j.Type = JSValueMBS.kJSTypeUndefined then
MsgBox ”undefined”
end if
Notes: The unique undefined value.
Chapter 16
Login Items
16.1
class LSSharedFileListItemMBS
16.1.1
class LSSharedFileListItemMBS
Plugin Version: 9.8, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: The class for a list
item.
Notes: Requires Mac OS X 10.5.
16.1.2
Methods
16.1.3
DisplayName as string
Plugin Version: 9.8, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: Obtain item’s display
name.
Example:
dim l as new LSSharedFileListMBS(LSSharedFileListMBS.kRecentDocumentItems)
if l.Handle=0 then
MsgBox ”Failed to get list.”
else
dim a(-1) as LSSharedFileListItemMBS = l.Snapshot
dim lines(-1) as string
for each x as LSSharedFileListItemMBS in a
lines.append x.DisplayName
next
437
438
CHAPTER 16. LOGIN ITEMS
MsgBox Join(lines, EndOfLine)
end if
16.1.4
Icon as Variant
Plugin Version: 9.8, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: Obtain item’s icon.
Notes: Returns an IconMBS object.
16.1.5
ID as UInt32
Plugin Version: 9.8, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: Obtain unique item
id.
Example:
dim l as new LSSharedFileListMBS(LSSharedFileListMBS.kSessionLoginItems)
if l.Handle=0 then
MsgBox ”Failed to get list.”
else
dim a(-1) as LSSharedFileListItemMBS = l.Snapshot
dim lines(-1) as string
for each x as LSSharedFileListItemMBS in a
lines.append x.DisplayName+”: ”+str(x.ID)
next
MsgBox Join(lines, EndOfLine)
end if
16.1.6
Resolve(flags as UInt32) as folderitem
Plugin Version: 9.8, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: Resolve item and
return its folderitem.
Example:
dim l as new LSSharedFileListMBS(LSSharedFileListMBS.kRecentDocumentItems)
if l.Handle=0 then
MsgBox ”Failed to get list.”
else
dim a(-1) as LSSharedFileListItemMBS = l.Snapshot
16.1. CLASS LSSHAREDFILELISTITEMMBS
439
dim lines(-1) as string
for each x as LSSharedFileListItemMBS in a
lines.append x.Resolve(0).AbsolutePath
next
MsgBox Join(lines, EndOfLine)
end if
Notes: Pass values like 0, kNoUserInteraction, kDoNotMountVolumes or kDoNotMountVolumes+kNoUserInteraction.
16.1.7
ResolveURL(flags as UInt32) as string
Plugin Version: 9.8, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: Resolve item and
return its URL.
Example:
dim l as new LSSharedFileListMBS(LSSharedFileListMBS.kRecentDocumentItems)
if l.Handle=0 then
MsgBox ”Failed to get list.”
else
dim a(-1) as LSSharedFileListItemMBS = l.Snapshot
dim lines(-1) as string
for each x as LSSharedFileListItemMBS in a
lines.append x.ResolveURL(x.kNoUserInteraction)
next
MsgBox Join(lines, EndOfLine)
end if
Notes: Pass values like 0, kNoUserInteraction, kDoNotMountVolumes or kDoNotMountVolumes+kNoUserInteraction.
440
CHAPTER 16. LOGIN ITEMS
16.1.8
Properties
16.1.9
Handle as Integer
Plugin Version: 9.8, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: The internal reference
to the item.
Notes: (Read and Write property)
16.1.10
Lasterror as Integer
Plugin Version: 9.8, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: The last error code.
Notes: (Read and Write property)
16.1.11
ItemHidden as boolean
Plugin Version: 9.8, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: Is item hidden in UI?
Example:
dim l as new LSSharedFileListMBS(LSSharedFileListMBS.kSessionLoginItems)
if l.Handle=0 then
MsgBox ”Failed to get list.”
else
dim a(-1) as LSSharedFileListItemMBS = l.Snapshot
dim lines(-1) as string
for each x as LSSharedFileListItemMBS in a
lines.append x.DisplayName+”: ”+str(x.ItemHidden)
next
MsgBox Join(lines, EndOfLine)
end if
Notes: (Read and Write computed property)
16.1.12
LoginItemHidden as boolean
Plugin Version: 9.8, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: Should UI hide login
item’s window?
Example:
16.1. CLASS LSSHAREDFILELISTITEMMBS
dim l as new LSSharedFileListMBS(LSSharedFileListMBS.kSessionLoginItems)
if l.Handle=0 then
MsgBox ”Failed to get list.”
else
dim a(-1) as LSSharedFileListItemMBS = l.Snapshot
dim lines(-1) as string
for each x as LSSharedFileListItemMBS in a
lines.append x.DisplayName+”: ”+str(x.LoginItemHidden)
next
MsgBox Join(lines, EndOfLine)
end if
Notes:
Requires Mac OS X 10.6.
(Read and Write computed property)
16.1.13
Constants
16.1.14
kDoNotMountVolumes = 2
Plugin Version: 9.8. Function: One of the flags for resolve.
Notes: do not mount volumes during resolution
16.1.15
kNoUserInteraction = 1
Plugin Version: 9.8. Function: One of the flags for resolve.
Notes: no user interaction during resolution
441
442
CHAPTER 16. LOGIN ITEMS
16.2
class LSSharedFileListMBS
16.2.1
class LSSharedFileListMBS
Plugin Version: 9.8, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: The shared list class.
Notes:
The shared file list API is for sharing and storing list of references to file system objects. The shared file
list is a persistent list of objects, where each item has assigned display name, icon, and url as well as other
optional properties.
Each list can also have various properties attached.
Requires Mac OS X 10.5.
16.2.2
Methods
16.2.3
Constructor(type as Integer)
Plugin Version: 9.8, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: Creates shared file
list reference to be used for changing list and reading its various properties.
Notes: type: A constant indicating list type to create. See the constants in this class.
16.2.4
GetSeedValue as UInt32
Plugin Version: 9.8, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: Returns seed value
of the shared list.
16.2.5
InsertFile(AfterItem as LSSharedFileListItemMBS, DisplayName as string,
Icon as object, file as folderitem) as LSSharedFileListItemMBS
Plugin Version: 9.8, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: Insert item into
shared list.
Example:
// Add iPhoto to launch items
// pick app
dim app as FolderItem = SpecialFolder.Applications.Child(”iPhoto.app”)
// get list object
dim l as new LSSharedFileListMBS(LSSharedFileListMBS.kSessionLoginItems)
16.2. CLASS LSSHAREDFILELISTMBS
443
// insert file
dim item as LSSharedFileListItemMBS = l.InsertFile(l.kLSSharedFileListItemBeforeFirst, ”Launch iPhoto”,
nil, app)
// check error
if l.Lasterror = 0 then
MsgBox ”OK”
else
MsgBox ”Failed: ”+str(l.Lasterror)
end if
Notes:
Inserts item into shared list at specified location. If the item already exists in the list it will be moved and
its icon, display name and properties will be updated.
AfterItem: Item after which new item has to be inserted. To insert at the beginning of the list use kLSSharedFileListItemBeforeFirst or to insert at the end of the list use kLSSharedFileListItemLast.
DisplayName: Display name of the new item. Can be NULL.
Icon: IconMBS of the new item. Can be nil.
File: Folderitem of the new item.
16.2.6
InsertURL(AfterItem as LSSharedFileListItemMBS, DisplayName as string,
Icon as object, URL as string) as LSSharedFileListItemMBS
Plugin Version: 9.8, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: Insert item into
shared list.
Notes:
Inserts item into shared list at specified location. If the item already exists in the list it will be moved and
its icon, display name and properties will be updated.
AfterItem: Item after which new item has to be inserted. To insert at the beginning of the list use kLSSharedFileListItemBeforeFirst or to insert at the end of the list use kLSSharedFileListItemLast.
DisplayName: Display name of the new item. Can be ””.
Icon: IconMBS object for the icon. Can be nil.
URL: URL of the new item.
444
16.2.7
CHAPTER 16. LOGIN ITEMS
kLSSharedFileListItemBeforeFirst as LSSharedFileListItemMBS
Plugin Version: 9.8, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: A virtual item
reference for inserting new item at beginning of the list.
Example:
dim n as LSSharedFileListItemMBS = LSSharedFileListMBS.kLSSharedFileListItemBeforeFirst
MsgBox str(n.Handle) // a special handle value for this virtual item: 1
16.2.8
kLSSharedFileListItemLast as LSSharedFileListItemMBS
Plugin Version: 9.8, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: A virtual item
reference for inserting new item at end of the list.
Example:
dim n as LSSharedFileListItemMBS = LSSharedFileListMBS.kLSSharedFileListItemLast
MsgBox str(n.Handle) // a special handle value for this virtual item: 2
16.2.9
Move(item as LSSharedFileListItemMBS, MoveAfterItem as LSSharedFileListItemMBS)
Plugin Version: 9.8, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: Moves item at
specified location.
Notes:
item: Item to move.
MoveAfterItem: New icon of the new item. Use kLSSharedFileListItemBeforeFirst and kLSSharedFileListItemLast to move at the beginning or the end of the shared list.
16.2.10
Remove(item as LSSharedFileListItemMBS)
Plugin Version: 9.8, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: Remove item from
shared list.
Example:
// Remove iPhoto from launch items
// get list object
dim l as new LSSharedFileListMBS(LSSharedFileListMBS.kSessionLoginItems)
// get items
16.2. CLASS LSSHAREDFILELISTMBS
445
dim items(-1) as LSSharedFileListItemMBS = l.Snapshot
// check all items
for each item as LSSharedFileListItemMBS in items
dim file as FolderItem = item.Resolve(LSSharedFileListItemMBS.kNoUserInteraction)
if file<>nil then
if file.Name = ”iPhoto.app” then
l.Remove item
if l.Lasterror = 0 then
MsgBox ”OK”
else
MsgBox ”Error: ”+str(l.Lasterror)
end if
Return
end if
end if
next
16.2.11
RemoveAllItems
Plugin Version: 9.8, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: Remove all items
from shared list.
16.2.12
SetAuthorization(handle as Integer)
Plugin Version: 9.8, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: Set authorization
reference for the shared list.
Notes: Before attempting to perform a privileged operation on the shared list caller must authorize appropriate rights. For example, modifying kGlobalLoginItems list requires ”system.global-login-items.” right
authorized.
16.2.13
Snapshot as LSSharedFileListItemMBS()
Plugin Version: 9.8, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: Creates snapshot
array, which is list of all items at the moment this method was called.
See also:
• 16.2.14 Snapshot(byref seed as UInt32) as LSSharedFileListItemMBS()
446
446
16.2.14
CHAPTER 16. LOGIN ITEMS
Snapshot(byref seed as UInt32) as LSSharedFileListItemMBS()
Plugin Version: 9.8, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: Creates snapshot
array, which is list of all items at the moment this method was called.
Notes: seed: Returned seed value at which snapshot was taken.
See also:
• 16.2.13 Snapshot as LSSharedFileListItemMBS()
16.2.15
Properties
16.2.16
Handle as Integer
445
Plugin Version: 9.8, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: The internal reference
to the list.
Notes: (Read and Write property)
16.2.17
Lasterror as Integer
Plugin Version: 9.8, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: The last error code.
Notes: (Read and Write property)
16.2.18
RecentItemsMaxAmount as Integer
Plugin Version: 9.8, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: Maximum amount
of items in the list.
Notes: (Read and Write computed property)
16.2.19
VolumesComputerVisible as boolean
Plugin Version: 9.8, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: Is Computer item
visible in favorite volumes list?
Notes: (Read and Write computed property)
16.2.20
VolumesIDiskVisible as boolean
Plugin Version: 9.8, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: Is iDisk item visible
in favorite volumes list.
16.2. CLASS LSSHAREDFILELISTMBS
447
Notes: (Read and Write computed property)
16.2.21
VolumesNetworkVisible as boolean
Plugin Version: 9.8, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: Is Network item
visible in favorite volumes list?
Notes: (Read and Write computed property)
16.2.22
Events
16.2.23
Changed
Plugin Version: 9.8, Console & Web: No, Mac: Yes, Win: No, Linux: No. Function: The event called
whenever the list is changed by an application.
16.2.24
Constants
16.2.25
kFavoriteItems = 2
Plugin Version: 9.8. Function: One of the list type constants.
Example:
dim l as new LSSharedFileListMBS(LSSharedFileListMBS.kFavoriteItems)
if l.Handle=0 then
MsgBox ”Failed to get list.”
else
dim a(-1) as LSSharedFileListItemMBS = l.Snapshot
dim lines(-1) as string
for each x as LSSharedFileListItemMBS in a
lines.append x.DisplayName
next
MsgBox Join(lines, EndOfLine)
end if
448
16.2.26
CHAPTER 16. LOGIN ITEMS
kFavoriteVolumes = 1
Plugin Version: 9.8. Function: One of the list type constants.
Example:
dim l as new LSSharedFileListMBS(LSSharedFileListMBS.kFavoriteVolumes)
if l.Handle=0 then
MsgBox ”Failed to get list.”
else
dim a(-1) as LSSharedFileListItemMBS = l.Snapshot
dim lines(-1) as string
for each x as LSSharedFileListItemMBS in a
lines.append x.DisplayName
next
MsgBox Join(lines, EndOfLine)
end if
16.2.27
kGlobalLoginItems = 7
Plugin Version: 9.8. Function: One of the list type constants.
Example:
dim l as new LSSharedFileListMBS(LSSharedFileListMBS.kGlobalLoginItems)
if l.Handle=0 then
MsgBox ”Failed to get list.”
else
dim a(-1) as LSSharedFileListItemMBS = l.Snapshot
dim lines(-1) as string
for each x as LSSharedFileListItemMBS in a
lines.append x.DisplayName
next
MsgBox Join(lines, EndOfLine)
end if
16.2. CLASS LSSHAREDFILELISTMBS
16.2.28
kRecentApplicationItems = 3
Plugin Version: 9.8. Function: One of the list type constants.
Example:
dim l as new LSSharedFileListMBS(LSSharedFileListMBS.kRecentApplicationItems)
if l.Handle=0 then
MsgBox ”Failed to get list.”
else
dim a(-1) as LSSharedFileListItemMBS = l.Snapshot
dim lines(-1) as string
for each x as LSSharedFileListItemMBS in a
lines.append x.DisplayName
next
MsgBox Join(lines, EndOfLine)
end if
16.2.29
kRecentDocumentItems = 4
Plugin Version: 9.8. Function: One of the list type constants.
Example:
dim l as new LSSharedFileListMBS(LSSharedFileListMBS.kRecentDocumentItems)
if l.Handle=0 then
MsgBox ”Failed to get list.”
else
dim a(-1) as LSSharedFileListItemMBS = l.Snapshot
dim lines(-1) as string
for each x as LSSharedFileListItemMBS in a
lines.append x.DisplayName
next
MsgBox Join(lines, EndOfLine)
end if
449
450
16.2.30
CHAPTER 16. LOGIN ITEMS
kRecentServerItems = 5
Plugin Version: 9.8. Function: One of the list type constants.
Example:
dim l as new LSSharedFileListMBS(LSSharedFileListMBS.kRecentServerItems)
if l.Handle=0 then
MsgBox ”Failed to get list.”
else
dim a(-1) as LSSharedFileListItemMBS = l.Snapshot
dim lines(-1) as string
for each x as LSSharedFileListItemMBS in a
lines.append x.DisplayName
next
MsgBox Join(lines, EndOfLine)
end if
16.2.31
kSessionLoginItems = 6
Plugin Version: 9.8. Function: One of the list type constants.
Example:
dim l as new LSSharedFileListMBS(LSSharedFileListMBS.kSessionLoginItems)
if l.Handle=0 then
MsgBox ”Failed to get list.”
else
dim a(-1) as LSSharedFileListItemMBS = l.Snapshot
dim lines(-1) as string
for each x as LSSharedFileListItemMBS in a
lines.append x.DisplayName
next
MsgBox Join(lines, EndOfLine)
end if
Chapter 17
Media Keys
17.1
class MediaKeysMBS
17.1.1
class MediaKeysMBS
Plugin Version: 11.2, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: Catch some special
keys with this class.
Example:
dim m as MediaKeysMBS // global property!
// app initialization
m = new MediaKeysMBS
// set which keys to watch for
m.Keys(MediaKeysMBS.kMediaKeyEject) = MediaKeysMBS.kModeEventAndBlock
// and start
m.startWatchingMediaKeys
Notes:
First written to catch play, fast and rewind keys from Apple keyboards.
Later extended to also catch other keys.
Still not all keys are available on all keyboards.
Please have only instance of this class running your application.
451
452
CHAPTER 17. MEDIA KEYS
17.1.2
Methods
17.1.3
Constructor
Plugin Version: 11.2, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: Initializes the key
watcher.
17.1.4
Keys(keyCode as Integer) as Integer
Plugin Version: 11.2, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: Which keys should
be intercepted and handled by your application.
Example:
dim m as new MediaKeysMBS // your MediaKeys object
// watch for this key
m.Keys(MediaKeysMBS.kMediaKeyEject) = MediaKeysMBS.kModeEventAndBlock
Notes: (Read and Write computed property)
17.1.5
startWatchingMediaKeys
Plugin Version: 11.2, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: Starts watching for
keys.
Example:
dim m as MediaKeysMBS // global property!
// app initialization
m = new MediaKeysMBS
m.Keys(MediaKeysMBS.kMediaKeyEject) = MediaKeysMBS.kModeEventAndBlock
m.startWatchingMediaKeys
17.1.6
stopWatchingMediaKeys
Plugin Version: 11.2, Console & Web: Yes, Mac: Yes, Win: No, Linux: No. Function: Stops watching for
keys.
Example:
17.1. CLASS MEDIAKEYSMBS
453
dim m as MediaKeysMBS // global property
// when closing media window
m.stopWatchingMediaKeys
Notes: The destructor calls this for cleanup.
17.1.7
Events
17.1.8
receivedMediaKeyEvent(e as NSEventMBS, keyCode as Integer, keyFlags
as Integer, keyState as Integer, keyRepeat as Integer)
Plugin Version: 11.2, Console & Web: No, Mac: Yes, Win: No, Linux: No. Function: The event called
when the user uses one of the special keys we listen for.
Notes:
If you don’t get the event, did you make sure all conditions are right?
• Requires Mac OS X 10.5
• Keys(x) set to kModeEventAndBlock or kModeEventAndPass for the keys you need?
• startWatchingMediaKeys called?
• your object is still alive in your application?
17.1.9
17.1.10
Constants
kMediaKeyBrightnessDown = 3
Plugin Version: 11.2. Function: One of the key constants.
Example:
dim m as new MediaKeysMBS // your MediaKeys object
// watch for this key
m.Keys(MediaKeysMBS.kMediaKeyBrightnessDown) = MediaKeysMBS.kModeEventAndBlock
454
17.1.11
CHAPTER 17. MEDIA KEYS
kMediaKeyBrightnessUp = 2
Plugin Version: 11.2. Function: One of the key constants.
Example:
dim m as new MediaKeysMBS // your MediaKeys object
// watch for this key
m.Keys(MediaKeysMBS.kMediaKeyBrightnessUp) = MediaKeysMBS.kModeEventAndBlock
17.1.12
kMediaKeyCapsLock = 4
Plugin Version: 11.2. Function: One of the key constants.
Example:
dim m as new MediaKeysMBS // your MediaKeys object
// watch for this key
m.Keys(MediaKeysMBS.kMediaKeyCapsLock) = MediaKeysMBS.kModeEventAndBlock
Notes: Caps Lock
17.1.13
kMediaKeyContrastDown = 12
Plugin Version: 11.2. Function: One of the key constants.
Example:
dim m as new MediaKeysMBS // your MediaKeys object
// watch for this key
m.Keys(MediaKeysMBS.kMediaKeyContrastDown) = MediaKeysMBS.kModeEventAndBlock
17.1.14
kMediaKeyContrastUp = 11
Plugin Version: 11.2. Function: One of the key constants.
Example:
dim m as new MediaKeysMBS // your MediaKeys object
// watch for this key
17.1. CLASS MEDIAKEYSMBS
m.Keys(MediaKeysMBS.kMediaKeyContrastUp) = MediaKeysMBS.kModeEventAndBlock
17.1.15
kMediaKeyDownArrow = 9
Plugin Version: 11.2. Function: One of the key constants.
Example:
dim m as new MediaKeysMBS // your MediaKeys object
// watch for this key
m.Keys(MediaKeysMBS.kMediaKeyDownArrow) = MediaKeysMBS.kModeEventAndBlock
17.1.16
kMediaKeyEject = 14
Plugin Version: 11.2. Function: One of the key constants.
Example:
dim m as new MediaKeysMBS // your MediaKeys object
// watch for this key
m.Keys(MediaKeysMBS.kMediaKeyEject) = MediaKeysMBS.kModeEventAndBlock
Notes: Eject key
17.1.17
kMediaKeyFast = 19
Plugin Version: 11.2. Function: One of the key constants.
Example:
dim m as new MediaKeysMBS // your MediaKeys object
// watch for this key
m.Keys(MediaKeysMBS.kMediaKeyFast) = MediaKeysMBS.kModeEventAndBlock
Notes: Fast key. On by default.
455
456
17.1.18
CHAPTER 17. MEDIA KEYS
kMediaKeyHelp = 5
Plugin Version: 11.2. Function: One of the key constants.
Example:
dim m as new MediaKeysMBS // your MediaKeys object
// watch for this key
m.Keys(MediaKeysMBS.kMediaKeyHelp) = MediaKeysMBS.kModeEventAndBlock
17.1.19
kMediaKeyIlluminationDown = 22
Plugin Version: 11.2. Function: One of the key constants.
Example:
dim m as new MediaKeysMBS // your MediaKeys object
// watch for this key
m.Keys(MediaKeysMBS.kMediaKeyIlluminationDown) = MediaKeysMBS.kModeEventAndBlock
17.1.20
kMediaKeyIlluminationToggle = 23
Plugin Version: 11.2. Function: One of the key constants.
Example:
dim m as new MediaKeysMBS // your MediaKeys object
// watch for this key
m.Keys(MediaKeysMBS.kMediaKeyIlluminationToggle) = MediaKeysMBS.kModeEventAndBlock
17.1.21
kMediaKeyIlluminationUp = 21
Plugin Version: 11.2. Function: One of the key constants.
Example:
dim m as new MediaKeysMBS // your MediaKeys object
// watch for this key
m.Keys(MediaKeysMBS.kMediaKeyIlluminationUp) = MediaKeysMBS.kModeEventAndBlock
17.1. CLASS MEDIAKEYSMBS
17.1.22
kMediaKeyLaunchPanel = 13
Plugin Version: 11.2. Function: One of the key constants.
Example:
dim m as new MediaKeysMBS // your MediaKeys object
// watch for this key
m.Keys(MediaKeysMBS.kMediaKeyLaunchPanel) = MediaKeysMBS.kModeEventAndBlock
17.1.23
kMediaKeyMute = 7
Plugin Version: 11.2. Function: One of the key constants.
Example:
dim m as new MediaKeysMBS // your MediaKeys object
// watch for this key
m.Keys(MediaKeysMBS.kMediaKeyMute) = MediaKeysMBS.kModeEventAndBlock
Notes: Sound Mute
17.1.24
kMediaKeyNext = 17
Plugin Version: 11.2. Function: One of the key constants.
Example:
dim m as new MediaKeysMBS // your MediaKeys object
// watch for this key
m.Keys(MediaKeysMBS.kMediaKeyNext) = MediaKeysMBS.kModeEventAndBlock
457
458
17.1.25
CHAPTER 17. MEDIA KEYS
kMediaKeyNumLock = 10
Plugin Version: 11.2. Function: One of the key constants.
Example:
dim m as new MediaKeysMBS // your MediaKeys object
// watch for this key
m.Keys(MediaKeysMBS.kMediaKeyNumLock) = MediaKeysMBS.kModeEventAndBlock
Notes: Num Lock key
17.1.26
kMediaKeyPlay = 16
Plugin Version: 11.2. Function: One of the key constants.
Example:
dim m as new MediaKeysMBS // your MediaKeys object
// watch for this key
m.Keys(MediaKeysMBS.kMediaKeyPlay) = MediaKeysMBS.kModeEventAndBlock
Notes: Play key. On by default.
17.1.27
kMediaKeyPower = 6
Plugin Version: 11.2. Function: One of the key constants.
Example:
dim m as new MediaKeysMBS // your MediaKeys object
// watch for this key
m.Keys(MediaKeysMBS.kMediaKeyPower) = MediaKeysMBS.kModeEventAndBlock
Notes: Power Key
17.1. CLASS MEDIAKEYSMBS
17.1.28
kMediaKeyPrevious = 18
Plugin Version: 11.2. Function: One of the key constants.
Example:
dim m as new MediaKeysMBS // your MediaKeys object
// watch for this key
m.Keys(MediaKeysMBS.kMediaKeyPrevious) = MediaKeysMBS.kModeEventAndBlock
Notes: Previous key
17.1.29
kMediaKeyRewind = 20
Plugin Version: 11.2. Function: One of the key constants.
Example:
dim m as new MediaKeysMBS // your MediaKeys object
// watch for this key
m.Keys(MediaKeysMBS.kMediaKeyRewind) = MediaKeysMBS.kModeEventAndBlock
Notes: Rewind Key. On by default.
17.1.30
kMediaKeySoundDown = 1
Plugin Version: 11.2. Function: One of the key constants.
Example:
dim m as new MediaKeysMBS // your MediaKeys object
// watch for this key
m.Keys(MediaKeysMBS.kMediaKeySoundDown) = MediaKeysMBS.kModeEventAndBlock
Notes: Sound down
459
460
17.1.31
CHAPTER 17. MEDIA KEYS
kMediaKeySoundUp = 0
Plugin Version: 11.2. Function: One of the key constants.
Example:
dim m as new MediaKeysMBS // your MediaKeys object
// watch for this key
m.Keys(MediaKeysMBS.kMediaKeySoundUp) = MediaKeysMBS.kModeEventAndBlock
Notes: Sound up
17.1.32
kMediaKeyUpArrow = 8
Plugin Version: 11.2. Function: One of the key constants.
Example:
dim m as new MediaKeysMBS // your MediaKeys object
// watch for this key
m.Keys(MediaKeysMBS.kMediaKeyUpArrow) = MediaKeysMBS.kModeEventAndBlock
17.1.33
kMediaKeyVideoMirror = 15
Plugin Version: 11.2. Function: One of the key constants.
Example:
dim m as new MediaKeysMBS // your MediaKeys object
// watch for this key
m.Keys(MediaKeysMBS.kMediaKeyVideoMirror) = MediaKeysMBS.kModeEventAndBlock
17.1.34
kModeBlock = 1
Plugin Version: 11.2. Function: One of the mode constants.
Notes: Block the event.
17.1. CLASS MEDIAKEYSMBS
17.1.35
kModeEventAndBlock = 2
Plugin Version: 11.2. Function: One of the mode constants.
Notes: Call the receivedMediaKeyEvent event and block the event.
17.1.36
kModeEventAndPass = 3
Plugin Version: 11.2. Function: One of the mode constants.
Notes: Call the receivedMediaKeyEvent event and pass the event to other applications.
17.1.37
kModePass = 0
Plugin Version: 11.2. Function: One of the mode constants.
Notes: Pass event to other applications.
461
462
CHAPTER 17. MEDIA KEYS
Chapter 18
QuickLook
463
464
CHAPTER 18. QUICKLOOK
Chapter 19
List of Questions in the FAQ
• 20.0.1 Can anyone help me convert seconds to time in this format hh:mm:ss?
475
• 20.0.2 How do I get the proper highlight color on Mac OS X for active/inactive selection?
476
• 20.0.3 How to catch delete key?
477
• 20.0.4 How to convert cmyk to rgb?
477
• 20.0.5 How to delete a folder?
479
• 20.0.6 How to detect if CPU if 64bit processor?
480
• 20.0.7 How to refresh a htmlviewer on Windows?
480
• 20.0.8 Is there an example for vector graphics in REALbasic?
481
• 20.0.9 Picture functions do not preserve resolution values?
481
• 20.0.10 A toolbox call needs a rect - how do I give it one?
482
• 20.0.11 API client not supported?
482
• 20.0.12 Can I access Access Database with Java classes?
483
• 20.0.13 Can I create PDF from Real Studio Report using DynaPDF?
484
• 20.0.14 Can I use AppleScripts in a web application?
484
• 20.0.15 Can I use graphics class with DynaPDF?
485
• 20.0.16 Can I use OGG with REALbasic?
485
• 20.0.17 Can I use sockets on a web application?
485
• 20.0.18 Can I use your ChartDirector plugin on a web application?
485
• 20.0.19 Can I use your DynaPDF plugin on a web application?
487
465
466
CHAPTER 19. LIST OF QUESTIONS IN THE FAQ
• 20.0.20 Can I use your plugin controls on a web application?
487
• 20.0.21 Can you get an unique machine ID?
487
• 20.0.22 ChartDirector: Alignment Specification
488
• 20.0.23 ChartDirector: Color Specification
488
• 20.0.24 ChartDirector: Font Specification
492
• 20.0.25 ChartDirector: Mark Up Language
495
• 20.0.26 ChartDirector: Parameter Substitution and Formatting
499
• 20.0.27 ChartDirector: Shape Specification
504
• 20.0.28 Copy styled text?
505
• 20.0.29 Do you have code to validate a credit card number?
505
• 20.0.30 Do you have plugins for X-Rite EyeOne, eXact or i1Pro?
506
• 20.0.31 Does SQL Plugin handle stored procedures with multiple result sets?
506
• 20.0.32 Does the plugin home home?
507
• 20.0.33 folderitem.absolutepath is limited to 255 chars. How can I get longer ones?
507
• 20.0.34 Future of editablemovie class?
508
• 20.0.35 Has anyone played round with using CoreImage to do things like add dissolve transitions say
when changing from one tab to another within a window?
508
• 20.0.36 How about Plugin support for older OS X?
509
• 20.0.37 How can I detect whether an Intel CPU is a 64bit CPU?
510
• 20.0.38 How can I disable the close box of a window on Windows?
511
• 20.0.39 How can I get all the environment variables from Windows?
511
• 20.0.40 How can i get similar behavior to Roxio Toast or iTunes where clicking a ’burn’ button allows
the next inserted blank CD-R to bypass the Finder and be accepted by my application?
512
• 20.0.41 How can I get text from a PDF?
512
• 20.0.42 How can I get text from a Word Document?
512
• 20.0.43 How can I get the item string for a given file creator?
513
• 20.0.44 How can I launch an app using it’s creator code?
514
• 20.0.45 How can I learn what shared libraries are required by a plugin on Linux?
514
• 20.0.46 How can I validate an email address?
515
• 20.0.47 How do I check if the QuickTime component for the JPEG exporting is available?
516
467
• 20.0.48 How do I check if the QuickTime component for the JPEG importing is available?
517
• 20.0.49 How do I check if the QuickTime component for the Sequence grabber is available?
518
• 20.0.50 How do I decode correctly an email subject?
518
• 20.0.51 How do I enable/disable a single tab in a tabpanel?
519
• 20.0.52 How do I find the root volume for a file?
520
• 20.0.53 How do I get the current languages list?
520
• 20.0.54 How do I get the Mac OS Version?
521
• 20.0.55 How do I get the printer name?
522
• 20.0.56 How do I make a metal window if RB does not allow me this?
522
• 20.0.57 How do I make a smooth color transition?
523
• 20.0.58 How do I read the applications in the dock app?
524
• 20.0.59 How do I truncate a file?
525
• 20.0.60 How do update a Finder’s windows after changing some files?
525
• 20.0.61 How to access a USB device directly?
525
• 20.0.62 How to add icon to file on Mac?
526
• 20.0.63 How to ask the Mac for the Name of the Machine?
526
• 20.0.64 How to automatically enable retina in my apps?
527
• 20.0.65 How to avoid leaks with Cocoa functions?
527
• 20.0.66 How to avoid trouble connecting to oracle database with SQL Plugin?
528
• 20.0.67 How to avoid
528
NSAutoreleaseNoPool console messages in threads?
• 20.0.68 How to bring app to front?
529
• 20.0.69 How to bring my application to front?
529
• 20.0.70 How to catch Control-C on Mac or Linux in a console app?
529
• 20.0.71 How to change name of application menu?
530
• 20.0.72 How to change the name in the menubar of my app on Mac OS X?
530
• 20.0.73 How to check if a folder/directory has subfolders?
531
• 20.0.74 How to check if Macbook runs on battery or AC power?
532
• 20.0.75 How to check if Microsoft Outlook is installed?
532
• 20.0.76 How to check on Mac OS which country or language is currently selected?
533
468
CHAPTER 19. LIST OF QUESTIONS IN THE FAQ
• 20.0.77 How to code sign my app with plugins?
534
• 20.0.78 How to collapse a window?
534
• 20.0.79 How to compare two pictures?
535
• 20.0.80 How to compile PHP library?
536
• 20.0.81 How to convert a BrowserType to a String with WebSession.Browser?
538
• 20.0.82 How to convert a EngineType to a String with WebSession.Engine?
538
• 20.0.83 How to convert a PlatformType to a String with WebSession.Platform?
539
• 20.0.84 How to convert a text to iso-8859-1 using the TextEncoder?
540
• 20.0.85 How to convert ChartTime back to Xojo date?
540
• 20.0.86 How to convert line endings in text files?
541
• 20.0.87 How to convert picture to string and back?
541
• 20.0.88 How to copy an array?
542
• 20.0.89 How to copy an dictionary?
543
• 20.0.90 How to copy parts of a movie to another one?
543
• 20.0.91 How to create a birthday like calendar event?
544
• 20.0.92 How to create a GUID?
545
• 20.0.93 How to create a Mac picture clip file?
545
• 20.0.94 How to create a PDF file in REALbasic?
546
• 20.0.95 How to create EmailAttachment for PDF Data in memory?
546
• 20.0.96 How to create PDF for image files?
547
• 20.0.97 How to CURL Options translate to Plugin Calls?
548
• 20.0.98 How to delete file with ftp and curl plugin?
549
• 20.0.99 How to detect display resolution changed?
549
• 20.0.100 How to detect retina?
549
• 20.0.101 How to disable force quit?
549
• 20.0.102 How to disable the error dialogs from Internet Explorer on javascript errors?
550
• 20.0.103 How to display a PDF file in REALbasic?
550
• 20.0.104 How to do a lottery in RB?
550
• 20.0.105 How to do an asycron DNS lookup?
551
469
• 20.0.106 How to draw a dushed pattern line?
552
• 20.0.107 How to draw a nice antialiased line?
553
• 20.0.108 How to draw with CGContextMBS using my own handle?
554
• 20.0.109 How to dump java class interface?
554
• 20.0.110 How to duplicate a picture with mask or alpha channel?
555
• 20.0.111 How to enable assistive devices?
556
• 20.0.112 How to encrypt a file with Blowfish?
556
• 20.0.113 How to extract text from HTML?
557
• 20.0.114 How to find empty folders in a folder?
557
• 20.0.115 How to find iTunes on a Mac OS X machine fast?
558
• 20.0.116 How to find network interface for a socket by it’s name?
558
• 20.0.117 How to find version of Microsoft Word?
559
• 20.0.118 How to fix CURL error 60/53 on connecting to server?
560
• 20.0.119 How to format double with n digits?
560
• 20.0.120 How to get a time converted to user time zone in a web app?
561
• 20.0.121 How to get an handle to the frontmost window on Windows?
561
• 20.0.122 How to get CFAbsoluteTime from date?
562
• 20.0.123 How to get client IP address on web app?
562
• 20.0.124 How to get fonts to load in charts on Linux?
563
• 20.0.125 How to get fonts to load in DynaPDF on Linux?
563
• 20.0.126 How to get GMT time and back?
564
• 20.0.127 How to get good crash reports?
564
• 20.0.128 How to get list of all threads?
564
• 20.0.129 How to get parameters from webpage URL in Real Studio Web Edition?
565
• 20.0.130 How to get Real Studio apps running Linux?
565
• 20.0.131 How to get the color for disabled textcolor?
566
• 20.0.132 How to get the current free stack space?
566
• 20.0.133 How to get the current timezone?
567
• 20.0.134 How to get the current window title?
568
470
CHAPTER 19. LIST OF QUESTIONS IN THE FAQ
• 20.0.135 How to get the cursor blink interval time?
569
• 20.0.136 How to get the list of the current selected files in the Finder?
570
• 20.0.137 How to get the Mac OS system version?
571
• 20.0.138 How to get the Mac OS Version using System.Gestalt?
571
• 20.0.139 How to get the screensize excluding the task bar?
572
• 20.0.140 How to get the size of the frontmost window on Windows?
572
• 20.0.141 How to get the source code of a HTMLViewer?
573
• 20.0.142 How to handle really huge images with GraphicsMagick or ImageMagick?
573
• 20.0.143 How to handle tab key for editable cells in listbox?
573
• 20.0.144 How to hard link MapKit framework?
575
• 20.0.145 How to have a PDF downloaded to the user in a web application?
575
• 20.0.146 How to hide all applications except mine?
576
• 20.0.147 How to hide script errors in HTMLViewer on Windows?
576
• 20.0.148 How to hide the grid/background/border in ChartDirector?
577
• 20.0.149 How to hide the mouse cursor on Mac?
577
• 20.0.150 How to insert image to NSTextView or TextArea?
577
• 20.0.151 How to jump to an anchor in a htmlviewer?
578
• 20.0.152 How to keep a movieplayer unclickable?
578
• 20.0.153 How to keep my web app from using 100% CPU time?
578
• 20.0.154 How to kill a process by name?
579
• 20.0.155 How to know how many CPUs are present?
579
• 20.0.156 How to know if a movie is finished?
580
• 20.0.157 How to know if QuickTime is installed on any target and can play MPEG 4 movies?
580
• 20.0.158 How to know if QuickTime is installed on any target?
581
• 20.0.159 How to know the calling function?
581
• 20.0.160 How to launch an app using it’s creator code?
582
• 20.0.161 How to launch disc utility?
582
• 20.0.162 How to make a lot of changes to a REAL SQL Database faster?
583
• 20.0.163 How to make a NSImage object for my retina enabled app?
583
471
• 20.0.164 How to make a window borderless on Windows?
583
• 20.0.165 How to make an alias using AppleEvents?
584
• 20.0.166 How to make an application smaller?
585
• 20.0.167 How to make AppleScripts much faster?
585
• 20.0.168 How to make double clicks on a canvas?
585
• 20.0.169 How to make my Mac not sleeping?
587
• 20.0.170 How to make my own registration code scheme?
588
• 20.0.171 How to make small controls on Mac OS X?
588
• 20.0.172 How to mark my Mac app as background only?
589
• 20.0.173 How to move a file or folder to trash?
590
• 20.0.174 How to move an application to the front using the creator code?
591
• 20.0.175 How to move file with ftp and curl plugin?
591
• 20.0.176 How to normalize string on Mac?
591
• 20.0.177 How to obscure the mouse cursor on Mac?
592
• 20.0.178 How to open icon file on Mac?
592
• 20.0.179 How to open PDF in acrobat reader?
593
• 20.0.180 How to open printer preferences on Mac?
593
• 20.0.181 How to open special characters panel on Mac?
594
• 20.0.182 How to optimize picture loading in Web Edition?
594
• 20.0.183 How to parse XML?
595
• 20.0.184 How to play audio in a web app?
595
• 20.0.185 How to pretty print xml?
596
• 20.0.186 How to print to PDF?
597
• 20.0.187 How to query Spotlight’s Last Open Date for a file?
597
• 20.0.188 How to quit windows?
598
• 20.0.189 How to read a CSV file correctly?
598
• 20.0.190 How to read the command line on windows?
599
• 20.0.191 How to render PDF pages with PDF Kit?
600
• 20.0.192 How to restart a Mac?
600
472
CHAPTER 19. LIST OF QUESTIONS IN THE FAQ
• 20.0.193 How to resume ftp upload with curl plugin?
601
• 20.0.194 How to rotate a PDF page with CoreGraphics?
601
• 20.0.195 How to rotate image with CoreImage?
602
• 20.0.196 How to run a 32 bit application on a 64 bit Linux?
603
• 20.0.197 How to save a quicktime movie as a reference movie?
603
• 20.0.198 How to save HTMLViewer to PDF with landscape orientation?
603
• 20.0.199 How to save RTFD?
604
• 20.0.200 How to scale a picture proportionally with mask?
604
• 20.0.201 How to scale a picture proportionally?
605
• 20.0.202 How to scale/resize a picture?
606
• 20.0.203 How to search with regex and use unicode codepoints?
607
• 20.0.204 How to see if a file is invisible for Mac OS X?
607
• 20.0.205 How to set cache size for SQLite or REALSQLDatabase?
608
• 20.0.206 How to set the modified dot in the window?
609
• 20.0.207 How to show a PDF file to the user in a Web Application?
609
• 20.0.208 How to show Keyboard Viewer programmatically?
609
• 20.0.209 How to show the mouse cursor on Mac?
610
• 20.0.210 How to shutdown a Mac?
611
• 20.0.211 How to sleep a Mac?
611
• 20.0.212 How to speed up rasterizer for displaying PDFs with DynaPDF?
612
• 20.0.213 How to use PDFLib in my RB application?
612
• 20.0.214 How to use quotes in a string?
612
• 20.0.215 How to use Sybase in Web App?
612
• 20.0.216 How to use the Application Support folder?
613
• 20.0.217 How to use the IOPMCopyScheduledPowerEvents function in Realbasic?
613
• 20.0.218 How to validate a GUID?
616
• 20.0.219 How to walk a folder hierarchie non recursively?
616
• 20.0.220 I got this error: PropVal, QDPictMBS.Name (property value), Type mismatch error. Expected CGDataProviderMBS, but got Variant, Name:QDPictMBS
617
473
• 20.0.221 I registered the MBS Plugins in my application, but later the registration dialog is shown.
618
• 20.0.222 I want to accept Drag & Drop from iTunes
618
• 20.0.223 I’m drawing into a listbox but don’t see something.
620
• 20.0.224 I’m searching for a method or so to move a window from position x.y to somewhere else on
the screen.
620
• 20.0.225 If I use one of your plug-ins under windows, would this then impose the use of dll after
compilation or my would my compiled soft still be a stand-alone single file software?
621
• 20.0.226 Is the fn key on a powerbook keyboard down?
621
• 20.0.227 Is there a case sensitive Dictionary?
621
• 20.0.228 Is there a way to use the MBS plugin to get only the visible item and folder count on a
volume?
622
• 20.0.229 Is there an easy way I can launch the Displays preferences panel?
622
• 20.0.230 Is there an easy way I can launch the Quicktime preferences panel?
623
• 20.0.231 List of Windows Error codes?
623
• 20.0.232 Midi latency on Windows problem?
623
• 20.0.233 My Xojo Web App does not launch. Why?
624
• 20.0.234 Pictures are not shown in my application. Why?
625
• 20.0.235 Realbasic doesn’t work with your plugins on Windows 98.
625
• 20.0.236 REALbasic or my RB application itself crashes on launch on Mac OS Classic. Why?
625
• 20.0.237 SQLDatabase not initialized error?
625
• 20.0.238 Textconverter returns only the first x characters. Why?
625
• 20.0.239 The type translation between CoreFoundation/Foundation and Realbasic data types.
626
• 20.0.240 Uploaded my web app with FTP, but it does not run on the server!
628
• 20.0.241 What classes to use for hotkeys?
628
• 20.0.242 What do I need for Linux to get picture functions working?
629
• 20.0.243 What does the NAN code mean?
629
• 20.0.244 What font is used as a ’small font’ in typical Mac OS X apps?
630
• 20.0.245 What is last plugin version to run on Mac OS X 10.4?
630
• 20.0.246 What is last plugin version to run on PPC?
631
• 20.0.247 What is the difference between Timer and WebTimer?
631
474
CHAPTER 19. LIST OF QUESTIONS IN THE FAQ
• 20.0.248 What is the list of Excel functions?
631
• 20.0.249 What is the replacement for PluginMBS?
632
• 20.0.250 What to do on Realbasic reporting a conflict?
632
• 20.0.251 What to do with a NSImageCacheException?
633
• 20.0.252 What to do with MySQL Error 2014?
633
• 20.0.253 What ways do I have to ping?
633
• 20.0.254 Where is CGGetActiveDisplayListMBS?
634
• 20.0.255 Where is CGGetDisplaysWithPointMBS?
634
• 20.0.256 Where is CGGetDisplaysWithRectMBS?
634
• 20.0.257 Where is CGGetOnlineDisplayListMBS?
634
• 20.0.258 Where is GetObjectClassNameMBS?
634
• 20.0.259 Where is NetworkAvailableMBS?
635
• 20.0.260 Where is StringHeight function in DynaPDF?
635
• 20.0.261 Where is XLSDocumentMBS class?
635
• 20.0.262 Where to get information about file formats?
636
• 20.0.263 Where to register creator code for my application?
636
• 20.0.264 Which Mac OS X frameworks are 64bit only?
636
• 20.0.265 Which plugins are 64bit only?
637
• 20.0.266 Why application doesn’t launch because of a missing ddraw.dll!?
637
• 20.0.267 Why application doesn’t launch because of a missing shlwapi.dll!?
637
• 20.0.268 Why do I hear a beep on keydown?
637
• 20.0.269 Why does folderitem.item return nil?
637
• 20.0.270 Why doesn’t showurl work?
638
• 20.0.271 Why have I no values in my chart?
638
• 20.0.272 Will application size increase with using plugins?
638
• 20.0.273 XLS: Custom format string guidelines
638
Chapter 20
The FAQ
20.0.1
Can anyone help me convert seconds to time in this format hh:mm:ss?
Plugin Version: all, Console & Web: No, Mac: Yes, Win: Yes, Linux: Yes. Answer: Sure, here’s a routine
I use (which has an advantage over the previously-posted Date-based solution in that you don’t have to rely
on the creation of an object – all that happens is some division and string concatenation):
Example:
Function SecsToTimeString(timeInSecs as Integer, padHours as boolean, padMinutes as boolean) as string
// Given an amount time (in seconds), generates a string representing that amount
// of time. The padHours and padMinutes parameters determine whether to display
// hours and minutes if their values are zero.
//
//
//
//
Examples:
timeInSecs = 90, padHours = true; returns ”00:01:30”
timeInSecs = 1, padHours = false, padMinutes = true; returns ”00:01”
timeInSecs = 3601, padMinutes = false; returns ”01:00:01”
dim hours, minutes, seconds as Integer
dim hoursString, minutesString as string
hours = timeInSecs / 3600
minutes = (timeInSecs mod 3600) / 60
seconds = timeInSecs mod 60
if hours = 0 then
if padHours then
hoursString = ”00:”
else
hoursString = ””
end if
else
475
476
CHAPTER 20. THE FAQ
hoursString = Format(hours, ”# # \:”)
end if
if minutes = 0 then
if hours <>0 or padMinutes then
minutesString = ”00:”
else
minutesString = ””
end if
else
minutesString = Format(minutes, ”00\:”)
end if
return hoursString + minutesString + Format(seconds, ”00”)
End Function
Notes: (from the rb mailinglist)
20.0.2
How do I get the proper highlight color on Mac OS X for active/inactive
selection?
Plugin Version: all, Console & Web: No, Mac: Yes, Win: Yes, Linux: Yes. Answer: You can use functions
from NSColor to get proper highlight color in RGB:
Example:
Function ProperHighlightColor(active as Boolean) As Color
# if TargetCocoa
Dim theColor As NSColorMBS
If active Then
theColor = NSColorMBS.alternateSelectedControlColor
Else
theColor = NSColorMBS.secondarySelectedControlColor
End If
Dim rgbColor As NSColorMBS = theColor.colorUsingColorSpaceName(NSColorSpaceMBS.NSCalibratedRGBColorSpace)
If rgbColor <>Nil Then
Dim red as Integer = rgbColor.redComponent * 255.0
Dim green as Integer = rgbColor.greenComponent * 255.0
Dim blue as Integer = rgbColor.blueComponent * 255.0
Return RGB(red, green, blue)
Else
Return HighlightColor
End If
# else
477
return HighlightColor
# endif
End Function
Notes: As you see we convert color to Calibrated RGB for best results.
See also:
• 20.0.3 How to catch delete key?
477
• 20.0.4 How to convert cmyk to rgb?
477
• 20.0.5 How to delete a folder?
479
• 20.0.6 How to detect if CPU if 64bit processor?
480
• 20.0.7 How to refresh a htmlviewer on Windows?
480
20.0.3
How to catch delete key?
Plugin Version: all, Console & Web: No, Mac: Yes, Win: Yes, Linux: Yes. Answer: The following is the
code in keydown event catches delete or backspace keys.
Example:
Function KeyDown(Key As String) As Boolean
if asc(key) = 8 or asc(key) = 127 then
MsgBox ”Delete”
Return true
end if
End Function
See also:
• 20.0.2 How do I get the proper highlight color on Mac OS X for active/inactive selection?
476
• 20.0.4 How to convert cmyk to rgb?
477
• 20.0.5 How to delete a folder?
479
• 20.0.6 How to detect if CPU if 64bit processor?
480
• 20.0.7 How to refresh a htmlviewer on Windows?
480
20.0.4
How to convert cmyk to rgb?
Plugin Version: all, Console & Web: No, Mac: Yes, Win: Yes, Linux: Yes. Answer:
478
CHAPTER 20. THE FAQ
The following is the code to convert cmyk values to an RGB color datatype.
It’s just a basic estimate of the color values. If you are looking for completely color accurate solution, this
is not it. It should work for most people. :)
Example:
Function CMYKToRGB(c as Integer, m as Integer, y as Integer, k as Integer) As color
// converts c,m,y,k values (0-100) to color data type RGB
// place this in a method. Supply C,M,Y,K values// it returns color datatype
dim color RGB as color
dim r, g, b as Integer
r=255-round(2.55*(c+k))
if r<0 then
r=0
end if
g=255-round(2.55*(m+k))
if g<0 then
g=0
end if
b=255-round(2.55*(y+k))
if b<0 then
b=0
end if
color RGB=RGB(r,g,b)
return color RGB
End Function
Notes: (from the rb mailinglist)
See also:
• 20.0.2 How do I get the proper highlight color on Mac OS X for active/inactive selection?
476
• 20.0.3 How to catch delete key?
477
• 20.0.5 How to delete a folder?
479
• 20.0.6 How to detect if CPU if 64bit processor?
480
• 20.0.7 How to refresh a htmlviewer on Windows?
480
479
20.0.5
How to delete a folder?
Plugin Version: all, Console & Web: No, Mac: Yes, Win: Yes, Linux: Yes. Answer: The following is the
code deletes a folder recursively.
Example:
Sub deletefolder(f as folderitem)
dim files(-1) as FolderItem
if f=nil then Return
// delete single file
if f.Directory=false then
f.Delete
Return
end if
// get a list of all items in that folder
dim i,c as Integer
c=F.Count
for i=1 to c
files.Append f.TrueItem(i)
next
// delete each item
for each fo as FolderItem in files
if fo=nil then
’ ignore
elseif fo.Directory then
deletefolder fo
else ’ file
fo.Delete
end if
next
f.Delete
End Sub
See also:
• 20.0.2 How do I get the proper highlight color on Mac OS X for active/inactive selection?
476
• 20.0.3 How to catch delete key?
477
• 20.0.4 How to convert cmyk to rgb?
477
• 20.0.6 How to detect if CPU if 64bit processor?
480
• 20.0.7 How to refresh a htmlviewer on Windows?
480
480
20.0.6
CHAPTER 20. THE FAQ
How to detect if CPU if 64bit processor?
Plugin Version: all, Console & Web: No, Mac: Yes, Win: Yes, Linux: Yes. Answer: Via CPUID you can
ask CPU:
Example:
dim c as new CPUIDMBS
if c.Flags(CPUIDMBS.kFeatureLM) then
MsgBox ”64-bit CPU”
else
MsgBox ”32-bit CPU”
end if
Notes: Should work on all intel compatible CPUs.
See also:
• 20.0.2 How do I get the proper highlight color on Mac OS X for active/inactive selection?
476
• 20.0.3 How to catch delete key?
477
• 20.0.4 How to convert cmyk to rgb?
477
• 20.0.5 How to delete a folder?
479
• 20.0.7 How to refresh a htmlviewer on Windows?
480
20.0.7
How to refresh a htmlviewer on Windows?
Plugin Version: all, Console & Web: No, Mac: Yes, Win: Yes, Linux: Yes. Answer: You can ask the
browser to reload the website with this code line:
Example:
call htmlViewer1.IERunJavaScriptMBS(”javascript:document.location.reload()”)
See also:
• 20.0.2 How do I get the proper highlight color on Mac OS X for active/inactive selection?
476
• 20.0.3 How to catch delete key?
477
• 20.0.4 How to convert cmyk to rgb?
477
• 20.0.5 How to delete a folder?
479
• 20.0.6 How to detect if CPU if 64bit processor?
480
481
20.0.8
Is there an example for vector graphics in REALbasic?
Plugin Version: all, Console & Web: No, Mac: Yes, Win: Yes, Linux: Yes. Answer: Try this example
inside the paint event of a window:
Example:
dim v as Group2D
dim r as RectShape
dim s as StringShape
const pi=3.14
s=new StringShape
s.Text=”Hello World!”
s.TextFont=”Geneva”
s.TextSize=24
s.FillColor=rgb(0,0,255)
s.Italic=true
s.y=5
s.x=0
r=new RectShape
r.X=0
r.y=0
r.Height=100
r.Width=180
r.BorderColor=rgb(255,0,0)
r.FillColor=rgb(0,255,0)
r.BorderWidth=5
r.Border=50
v=new Group2d
v.Append r
v.Append s
v.Rotation=pi*-20.0/180.0
v.x=150
v.y=150
g.DrawObject v
20.0.9
Picture functions do not preserve resolution values?
Plugin Version: all, Console & Web: No, Mac: Yes, Win: Yes, Linux: Yes. Answer: Yes, the picture
functions return pictures with no/default resolution values.
482
CHAPTER 20. THE FAQ
Example:
dim l as Picture = LogoMBS(500)
l.HorizontalResolution = 300
l.VerticalResolution = 300
dim r as Picture = l.Rotate90MBS
MsgBox str(r.HorizontalResolution)+” x ”+str(r.VerticalResolution)
r.HorizontalResolution = l.HorizontalResolution
r.VerticalResolution = l.VerticalResolution
MsgBox str(r.HorizontalResolution)+” x ”+str(r.VerticalResolution)
Notes:
So please fix them yourself after calling a function.
Maybe in the future this changes, but currently you can’t really set this easily from plugin code.
20.0.10
A toolbox call needs a rect - how do I give it one?
Plugin Version: all, Console & Web: No, Mac: Yes, Win: Yes, Linux: No. Answer: Fill a memoryblock
like this:
Example:
Dim MB As Memoryblock
MB = NewMemoryBlock(8)
MB.Short(0) = window1.Top
MB.Short(2) = window1.Left
MB.Short(4) = window1.Height+window1.Top // bottom
MB.Short(6) = window1.Width+window1.Left // right
20.0.11
API client not supported?
Plugin Version: all, Console & Web: No, Mac: Yes, Win: Yes, Linux: Yes. Answer: If you get this
exception message on SQLConnectionMBS.Connect, we may have a problem.
Notes:
First case is that the given thing is not supported (e.g. MS SQL directly on Mac).
483
Second case is that the plugin compilation went wrong and the support for the database was not linked into
the plugin. Like MySQL missing or MS SQL on Windows missing. In that case please contact us to fix the
plugin.
20.0.12
Can I access Access Database with Java classes?
Plugin Version: all, Console & Web: No, Mac: No, Win: Yes, Linux: No. Answer: You can use ucanaccess
to access databases created with Microsoft
Example:
dim options(-1) as string
// load all the jar files we have in a folder called java:
dim appFolder as FolderItem = GetFolderItem(””)
Dim count as Integer = appFolder.Parent.Child(”java”).Count
dim libjs() as string
For i as Integer = 1 to count
Dim f As FolderItem = appFolder.Parent.Child(”java”).item(i)
If f <>Nil and f.Exists Then
libjs.append f.NativePath+”;”
End If
Next
// now init virtual machine
dim librery as string = Join(libjs, ””)
dim vm as new JavaVMMBS(librery)
if vm.Handle = 0 then
MsgBox ”Failed to initialize virtual machine”
else
// now make a new database connection with ucanaccess
dim d as new JavaDatabaseMBS(vm,”net.ucanaccess.jdbc.UcanaccessDriver”)
Dim DbFile as FolderItem = appFolder.Parent.Child(”Database11.accdb”)
dim j as JavaConnectionMBS = d.getConnection(”jdbc:ucanaccess://”+DbFile.NativePath)
// select and show values
dim r as JavaResultSetMBS = j.MySelectSQL(”Select * From test”)
while r.NextRecord
MsgBox r.getString(”FirstName”) +” ”+ r.getString(”LastName”)
wend
end if
Exception e as JavaExceptionMBS
484
CHAPTER 20. THE FAQ
MsgBox e.message+” errorcode: ”+str(e.ErrorNumber)
Notes:
see website:
http://ucanaccess.sourceforge.net/site.html
20.0.13
Can I create PDF from Real Studio Report using DynaPDF?
Plugin Version: all, Console & Web: No, Mac: Yes, Win: Yes, Linux: Yes. Answer: Sorry, no. We can’t
provide a graphics subclass from plugin.
Notes:
The is a feature request to allow graphics subclasses:
Feedback case 11391: feedback://showreport?report id=11391
20.0.14
Can I use AppleScripts in a web application?
Plugin Version: all, Console & Web: No, Mac: Yes, Win: Yes, Linux: Yes. Answer: Yes, but they run on
the server, not on the client.
Example:
dim a as new AppleScriptMBS
// query my application name
a.Compile ”tell application ””System Events”” to return name of current application”
// run
a.Execute
// show result
label1.text = a.Result
// shows something like ”My Application.fcgi.debug”
Notes: This can be useful to control the server from remote, if and only if the your sever is running Mac
OS X.
485
20.0.15
Can I use graphics class with DynaPDF?
Plugin Version: all, Console & Web: No, Mac: Yes, Win: Yes, Linux: Yes. Answer: Sorry, no. We can’t
provide a graphics subclass from plugin.
Notes:
The is a feature request to allow graphics subclasses:
Feedback case 11391: feedback://showreport?report id=11391
20.0.16
Can I use OGG with REALbasic?
Plugin Version: all, Console & Web: No, Mac: Yes, Win: Yes, Linux: No. Answer: There is a QuickTime
plugin for OGG which works with REALbasic.
Notes: That should be a solution for playback and recording on Mac and Windows.
20.0.17
Can I use sockets on a web application?
Plugin Version: all, Console & Web: No, Mac: Yes, Win: Yes, Linux: Yes. Answer: Yes, but they run on
the server, not on the client.
Notes:
You can use HTTPSocket, SMTPSocket, POP3Socket, SMTPSecureSocket, SecurePOP3Socket, EasyTCPSocket, EasyUDPSocket, AutoDiscovery, our Bonjour classes or our CURL* classes. But all of them work
on the server, not on the client.
This means if you search for a printer with Bonjour, you can find the printers in the local network on your
server hosting site. Using SMTPSocket may be a good idea for sending emails from the server like notifications.
20.0.18
Can I use your ChartDirector plugin on a web application?
Plugin Version: all, Console & Web: No, Mac: Yes, Win: Yes, Linux: Yes. Answer: Yes, our ChartDirector
plugin works just fine on the Real Studio Web Edition.
Example:
// The data for the pie chart
dim data(-1) as Double=array(55.0, 18.0, 25.0, 22.0, 18.0, 30.0, 35.0)
// The labels for the pie chart, Words are choosen random to check font!
dim labels(-1) as string=array(”Germany”,”Italy”,”France”,”Spain”,”UK”,”Poland”,”Russia”)
// The colors to use for the sectors
486
CHAPTER 20. THE FAQ
dim colors(-1) as Integer
colors.Append
colors.Append
colors.Append
colors.Append
&
&
&
&
h66aaee
heebb22
hbbbbbb
h8844ff
if TargetLinux then
CDBaseChartMBS.SetFontSearchPath ”/usr/share/fonts/truetype/msttcorefonts”
end if
// Create a PieChart object of size 360 x 300 pixels
dim c as new CDPieChartMBS(700, 600)
c.setBackground(c.linearGradientColor(0, 0, 0, c.getHeight(), & h0000cc, & h000044))
c.setRoundedFrame(& hffffff, 16)
dim tt as CDTextBoxMBS = c.addTitle(”ChartDirector Demonstration”, ”timesbi.ttf”, 18)
tt.setMargin(0, 0, 16, 0)
tt.setFontColor(& hFFFFFF)
// Set the center of the pie at (180, 140) and the radius to 100 pixels
c.setPieSize 350,300,150
// Set the sector colors
c.setColors(c.kDataColor, colors)
// Draw the pie in 3D with a pie thickness of 20 pixels
c.set3D(20)
dim t as CDTextBoxMBS = c.setLabelStyle(”arialbd.ttf”, 10, & h000000)
t.setBackground(CDPieChartMBS.kSameAsMainColor, CDPieChartMBS.kTransparent, CDPieChartMBS.softLighting(CDPieChartMBS.kRight, 0))
t.setRoundedCorners(8)
// Use local gradient shading for the sectors, with 5 pixels wide
// semi-transparent white (bbffffff) borders
c.setSectorStyle(CDPieChartMBS.kLocalGradientShading, & hbbffffff, 0)
// Set the pie data and the pie labels
c.setData data,labels
call c.setLabelStyle ”arialbd.ttf”,18
dim pic as picture = c.makeChartPicture
dim wp as new WebPicture(pic, Picture.FormatJPEG) // JPEG makes it smaller and faster
ImageView1.Picture=wp
487
Notes:
Be aware that our plugin produces pictures for you, which you assign to ImageViews. Tranfserring those
pictures takes time, so you can optimize that with using WebPicture class. There you can decide between
different compressions to improve speed (use JPEG instead of PNG).
e.g. if you use ubuntu, you can install the ttf-mscorefonts-installer package and call this method with
”/usr/share/fonts/truetype/msttcorefonts” as the path. No backslash on the end of a path, please.
20.0.19
Can I use your DynaPDF plugin on a web application?
Plugin Version: all, Console & Web: No, Mac: Yes, Win: Yes, Linux: Yes. Answer: Yes, our DynaPDF
plugin works just fine on the Real Studio Web Edition.
Notes:
PDF files are created on the server. You may want to offer a preview to the user which uses reduced resolution images to reduce the time to download the PDF.
See our Create PDF example for the Real Studio Web Edition.
http://www.monkeybreadsoftware.de/realbasic/webapps.shtml
20.0.20
Can I use your plugin controls on a web application?
Plugin Version: all, Console & Web: No, Mac: Yes, Win: Yes, Linux: Yes. Answer: No.
20.0.21
Can you get an unique machine ID?
Plugin Version: all, Console & Web: No, Mac: Yes, Win: Yes, Linux: Yes. Answer: There is nothing like
an unique machine ID.
Notes:
1:
You can use the MAC IDs of the network interfaces.
This can be changed by the user with software tools.
And the list of network interfaces changes if user reorder the interfaces.
2:
You can use the system folder creation date/time.
This may stay equal after cloning machines or after migration to
new PC.
488
CHAPTER 20. THE FAQ
3:
You can use the Mac Serialnumber.
Mac only and it can happen that a Mac does not have a serial
number.
4:
You can use the x86 CPU ID.
This is x86 CPU only and does not avoid running on the same CPU in
different PCs.
20.0.22
ChartDirector: Alignment Specification
Plugin Version: 8.2, Console & Web: No, Mac: Yes, Win: Yes, Linux: Yes. Answer: ChartDirector:
Alignment Specification
Notes:
In many ChartDirector objects, you may specify the alignment of the object’s content relative to its boundary. For example, for a TextBox object, you may specify the text’s alignment relative to the box boundary
by using TextBox.setAlignment.
The ChartDirector API defines several constants for the alignment options.
ConstantValueDescription
20.0.23
ChartDirector: Color Specification
Plugin Version: 8.2, Console & Web: No, Mac: Yes, Win: Yes, Linux: Yes. Answer: ChartDirector: Color
Specification
Notes:
Many functions in the ChartDirector API accept colors as parameters. ChartDirector supports colors specified in web and HTML compatible ARGB format, in which ARGB refers to the Alpha transparency, Red,
Green and Blue components of the color.
In addition to ARGB colors, ChartDirector supports ”dynamic” colors. A dynamic color is a color that
changes depending on the position of the pixels. The ”dynamic” colors that ChartDirector supports include
”pattern colors”, ”metal colors”, ”gradient colors”, ”zone colors” and ”dash line colors”.
ChartDirector supports specifying colors indirectly using ”palette colors”. When a ”palette color” is used,
the color is specified as an index to a palette. The actual color is looked up from the palette.ARGB Color
ARGB color consists of 4 components - alpha transparency, red, green and blue. The four components are
encoded as a 32-bit number, with each component occupying 8 bits. In hexadecimal notation, it is AAR-
489
BottomLeft
BottomCenter
BottomRight
Left
Center
Right
TopLeft
TopCenter
TopRight
Bottom
Top
TopLeft2
1
2
3
4
5
6
7
8
9
2
8
10
TopRight2
11
BottomLeft2
12
BottomRight2
13
The leftmost point on the bottom line.
The center point on the bottom line.
The rightmost point on the bottom line.
The leftmost point on the middle horizontal line.
The center point on the middle horizontal line.
The rightmost point on the middle horizontal line.
The leftmost point on the top line.
The center point on the top line.
The rightmost point on the top line.
The center point on the bottom line. Same as BottomCenter.
The center point on the top line. Same as TopCenter.
An alternative top-left position used in Axis.setTitlePos for axis title positioning only. For a vertical axis, TopLeft2 refers to refers to the left of the top
side, while TopLeft refers to the top of the left side. The reverse applies for a
horizontal axis.
An alternative top-right position used in Axis.setTitlePos for axis title positioning only. For a vertical axis, TopRight2 refers to refers to the right of the
top side, while TopRight refers to the top of the right side. The reverse applies
for a horizontal axis.
An alternative bottom-left position used in Axis.setTitlePos for axis title positioning only. For a vertical axis, BottomLeft2 refers to refers to the left of
the bottom side, while BottomLeft refers to the bottom of the left side. The
reverse applies for a horizontal axis.
An alternative bottom-right position used in Axis.setTitlePos for axis title
positioning only. For a vertical axis, BottomRight2 refers to refers to the right
of the bottom side, while BottomRight refers to the bottom of the right side.
The reverse applies for a horizontal axis.
RGGBB, where AA, RR, GG and BB are the alpha transparency, red, green and blue components.
Each component ranges from 00 - FF (0 - 255), representing its intensity. For example, pure red color is
00FF0000, pure green color is 0000FF00, and pure blue color is 000000FF. White color is 00FFFFFF, and
black color is 00000000.
Most programming language requires you to put special prefix in front of hexadecimal characters. For C++,
the prefix is ”0x”. For example, the syntax for the hexadecimal number 00FFFFFF is 0x00FFFFFF, or
simply 0xFFFFFF.
For the alpha transparency component, a zero value means the color is not transparent all at. This is equivalent to traditional RGB colors. A non-zero alpha transparency means the the color is partially transparent.
The larger the alpha transparency, the more transparent the color will be. If a partially transparent color is
used to draw something, the underlying background can still be seen.
For example, 80FF0000 is a partially transparent red color, while 00FF0000 is a non-transparent red color.
490
CHAPTER 20. THE FAQ
Note that ChartDirector’s ARGB color is web and HTML compatible. For example, red is FF0000, the same
as in HTML. There are many resources on the web that provide tables in which you can click a color and it
will show its HTML color code. These color codes can be used in ChartDirector.
If alpha transparency is FF (255), the color is totally transparent. That means the color is invisible. It does
not matter what the RGB components are. So in ChartDirector, only one totally transparent color is used
- FF000000. All other colors of the form FFnnnnnn are reserved to represent palette colors and dynamic
colors, and should not be interpreted as the normal ARGB colors.
The totally transparent color FF000000 is often used in ChartDirector to disable drawing something. For
example, if you want to disable drawing the border of a rectangle, you can set the border color to totally
transparent.
For convenience, ChartDirector defines a constant called Transparent, which is equivalent to FF000000.Pattern Color
A pattern color is a dynamic color that changes according to a 2D periodic pattern. When it is used to fill
an area, the area will look like being tiled with a wallpaper pattern.
Pattern colors are created using BaseChart.patternColor, BaseChart.patternColor2, DrawArea.patternColor
and DrawArea.patternColor2. The patternColor method creates pattern colors using an array of colors as a
bitmap. The patternColor2 method creates pattern colors by loading the patterns from image files.
These methods return a 32-bit integer acting as a handle to the pattern color. The handle can be used in
any ChartDirector API that expects a color as its input.Metal Color
A metal color is a color of which the brightness varies smoothly across the chart surface as to make the
surface looks shiny and metallic. ChartDirector supports using any color as the base color of the metal color.
In particular, using yellow and grey as the base colors will result in metal colors that look gold and silver.
Metal colors are most often used as background colors of charts. They are created using CDBaseChartMBS.metalColor, CDBaseChartMBS.goldColor and CDBaseChartMBS.silverColor. The first method allows you to
specify an arbitrary base color. The second and third methods use yellow and grey as the base colors,
resulting in gold and silver metal colors.
These methods return a 32-bit integer acting as a handle to the gradient color. The handle can be used in
any ChartDirector API that expects a color as its input.Gradient Color
A gradient color is a color that changes progressively across a direction.
Gradient colors are created using BaseChart.gradientColor, BaseChart.gradientColor2, DrawArea.gradientColor and DrawArea.gradientColor2. The gradientColor method creates a 2-point gradient color that changes
from color A to color B. The gradientColor2 method creates a multi-point gradient colors that changes from
color A to B to C ....
491
These methods return a 32-bit integer acting as a handle to the gradient color. The handle can be used in
any ChartDirector API that expects a color as its input.
One common use of multi-point gradient colors is to define colors that have metallic look and feel. Please
refer to DrawArea.gradientColor2 for details.Dash Line Colors
A dash line color is a color that switches on and off periodically. When used to draw a line, the line will
appear as a dash line.
Dash line colors are created using BaseChart.dashLineColor and DrawArea.dashLineColor. They accept a
line color and a dash pattern code as arguments, and return a 32-bit integer acting as a handle to the dash
line color. The handle can be used in any ChartDirector API that expects a color as its input.Zone Colors
A zone color is for XY charts only. It is a color that automatically changes upon reaching a data threshold
value along the x-axis or y-axis. Zone colors are created using Layer.xZoneColor, Layer.yZoneColor, XYChart.xZoneColor or XYChart.yZoneColor.Palette Colors
Palette colors are colors of the format FFFFnnnn, where the least significant 16 bits (nnnn) are the index
to the palette. A palette is simply an array of colors. For a palette color, the actual color is obtained by
looking up the palette using the index. For example, the color FFFF0001 is the second color in the palette
(first color is index 0).
The colors in the palette can be ARGB colors or ”dynamic” colors (pattern, gradient and dash line colors).
The first eight palette colors have special significance. The first three palette colors are the background
color, default line color, and default text color of the chart. The 4th to 7th palette colors are reserved for
future use. The 8th color is a special dynamic color that is equal to the data color of the ”current data set”.
The 9th color (index = 8) onwards are used for automatic data colors. For example, in a pie chart, if the
sector colors are not specified, ChartDirector will automatically use the 9th color for the first sector, the 10th
color for the second sector, and so on. Similarly, for a multi-line chart, if the line colors are not specified,
ChartDirector will use the 9th color for the first line, the 10th color for the second line, and so on.
The ChartDirector API defines several constants to facilitate using palette colors.
ConstantValueDescription
When a chart is created, it has a default palette. You may modify the palette using BaseChart.setColor,
BaseChart.setColors, or BaseChart.setColors2.
The advantages of using palette colors are that you can change the color schemes of the chart in one place.
ChartDirector comes with several built-in palettes represented by the following predefined constants.
492
CHAPTER 20. THE FAQ
Palette
FFFF0000
BackgroundColor
LineColor
TextColor
[ Reserved ]
FFFF0000
FFFF0001
FFFF0002
FFFF0003 - FFFF0006
SameAsMainColor
FFFF0007
DataColor
FFFF0008
The starting point of the palette. The first palette color is (Palette + 0). The
nth palette color is (Palette + n - 1).
The background color.
The default line color.
The default text color.
These palette positions are reserved. Future versions of ChartDirector may use
these palette positions for colors that have special significance.
A dynamic color that is equal to the data color of the current data set. This
color is useful for objects that are associated with data sets. For example, in
a pie chart, if the sector label background color is SameAsMainColor, its color
will be the same as the corresponding sector color.
The starting point for the automatic data color allocation.
ConstantDescription
defaultPalette
whiteOnBlackPalette
transparentPalette
20.0.24
An array of colors representing the default palette. This palette is designed for
drawing charts on white backgrounds (or lightly colored backgrounds).
An array of colors useful for drawing charts on black backgrounds (or darkly
colored backgrounds).
An array of colors useful drawing charts on white backgrounds (or lightly colored backgrounds). The data colors in this palette are all semi-transparent.
ChartDirector: Font Specification
Plugin Version: 8.2, Console & Web: No, Mac: Yes, Win: Yes, Linux: Yes. Answer: ChartDirector: Font
Specification
Notes:
Font Name
In ChartDirector, the font name is simply the file name that contains the font. For example, under the
Windows platform, the ”Arial” font is ”arial.ttf”, while the ”Arial Bold” font is ”arialbd.ttf”.
NOTE: Mac OS X Specific Information
In Mac OS X, in addition to ”.ttf”, ChartDirector also supports Mac OS X font file formats, such as Font
Suitcase files and Datafork files (.dfont). These files often contain multiple fonts. For example, the ”GillSans.dfont” file contains 6 fonts.
So in addition to the file name, an index is needed to determine the font. The index is specified by appending a ” | ” character to the font name, followed by the index number. For example, the third font in
”GillSans.dfont” is denoted as ”GillSans.dfont | 2”. (Note: The first font starts at 0.) If no index number is
provided, the first font is assumed.
ChartDirector also supports using Mac OS X Font Manager names. For example, one may use ”Gill Sans
Light Italic” instead of using ”GillSans.dfont | 1” as the font name. However, the Mac OS X Font Manager
493
is active only if someone has logged into the Mac GUI console, so this method is only recommended for
developing applications that run on the GUI console.
The sample programs that come with ChartDirector are designed to run on all operating systems, so they use
generic font file names (eg. ”arial.ttf”) instead of Mac OS X specific names. To allow them to run on Mac OS
X, ChartDirector on Mac OS X has a built-in table to map common font file names to Mac OS X font names:
”arial.ttf”, ”arialbd.ttf”, ”ariali.ttf” and ”arialbi.ttf” are mapped to ”Arial | 0” (Arial), ”Arial | 1” (Arial
Bold), ”Arial | 2” (Arial Italic) and ”Arial | 3” (Arial Bold Italic)
”times.ttf”, ”timesbd.ttf”, ”timesi.ttf” and ”timesbi.ttf” are mapped to ”Times New Roman | 0” (Times
New Roman), ”Times New Roman | 1” (Times New Roman Bold), ”Times New Roman | 2” (Times New
Roman Italic) and ”Times New Roman | 3” (Times New Roman Bold Italic)
”cour.ttf”, ”courbd.ttf”, ”couri.ttf” and ”courbi.ttf” are mapped to ”Courier New | 0” (Courier New),
”Courier New | 1” (Courier New Bold), ”Courier New | 2” (Courier New Italic) and ”Courier New | 3”
(Courier New Bold Italic)
Font Location
ChartDirector on Windows does not come with any font files. It relies on the operating system’s font files
in the ” [ windows ] \Fonts” directory. To see what fonts are installed in your operating system and their
file names, use the File Explorer to view that directory.
ChartDirector on Windows will also search for the font files in the ”fonts” subdirectory (if it exists) under
the directory where the ChartDirector DLL ”chartdir.dll” is installed. This is useful for private fonts. Also,
for some especially secure web servers, the web anonymous user may not have access to the ” [ windows ]
\Fonts” directory. In this case, you may copy the font files to the above subdirectory.
ChartDirector on Mac OS X relies on operating system font files in ”/Library/Fonts” and ”/System/Library/Fonts”.
ChartDirector on Linux, FreeBSD and Solaris assume the fonts files are in the ”fonts” subdirectory under
the directory where the ChartDirector shared object ”libchartdir.so” is installed. ChartDirector on Linux,
FreeBSD and Solaris come with a number of font files in the ”fonts” subdirectory.
To keep the download size small, ChartDirector on Linux, FreeBSD and Solaris only come with some commonly used fonts. You may download additional fonts from the Internet. In particular, the Microsoft fonts
at
http://sourceforge.net/project/showfiles.php?group id=34153& release id=105355
is highly recommended. Please refer to
http://www.microsoft.com/typography/faq/faq8.htm
on how you could use the fonts legally in your system.
494
CHAPTER 20. THE FAQ
ChartDirector supports True Type fonts (.ttf), Type 1 fonts (.pfa and .pfb) and Windows bitmap fonts
(.fon). On Mac OS X, ChartDirector also supports Font Suitcase and Datafork (.dfont) files. On Linux,
FreeBSD and Solaris, ChartDirector also supports Portable Compiled Fonts (.pcf fonts).
If you want ChartDirector to search other directories for the font files, you may list the directories in an
environment variable called ”FONTPATH”.
If you specify an absolute path name for the font file, ChartDirector will use the absolute path name and
will not search other directories.Artificial Boldening and Italicizing
Whereas most popular font comes with different styles for ”normal”, ”bold”, ”italic” and ”bold italic”, some
fonts only come with one style (the normal style). For example, the Monotype Corsiva font that comes with
MS Office only has the normal style (mtcorsva.ttf). For these cases, you may append the ”Bold” and/or
”Italic” words after the font file name (separated with a space) to ask ChartDirector to artificially bolden
and/or italicize the font. For example, you may specify the font name as ”mtcorsva.ttf Bold”.Font List
Instead of specifying a single font file as the font name, you may specify a list of font files as the font name,
separated by semi-colons. This is useful when using international characters that are only available in some
fonts.
For example, if you would like to use the Arial font (”arial.ttf”) for western characters, and the MingLiu
font ”mingliu.ttc” for Chinese characters (since the Arial font does not have Chinese characters), you may
specify the font name as ”arial.ttf;mingliu.ttc”. In this case, ChartDirector will try the Arial font first. If it
cannot find a certain character there, it will try the MingLiu font.Indirect Font Names
ChartDirector supports several special keywords for specifying the font name indirectly. When these keywords are used as font names, ChartDirector will look up the actual font names from a font table. The
keywords are as follows:
KeywordsDescription
”normal”
”bold”
”italic”
”boldItalic”
”fontN”
This default normal font, which is the first font in the font table. This is
initially mapped to ”arial.ttf” (Arial).
The default bold font, which is the second font in the font table. This is initially
mapped to ”arialbd.ttf” (Arial Bold).
The default italic font, which is the third font in the font table. This is initially
mapped to ”ariali.ttf” (Arial Italic).
The default bold-italic font, which is the fourth font in the font table. This is
initially mapped to ”arialbi.ttf” (Arial Bold Italic).
The (N + 1)th font in the font table (the first font is ”font0”).
The font table can be modified using BaseChart.setFontTable or DrawArea.setFontTable.
495
The advantage of using indirect font names is that you can change the fonts fonts in your charts in one
place.Font Index
Most font files contain one font. However, it is possible a font file contains multiple fonts (that is, a font
collection). For example, in True Type fonts, font files with extension ”.ttc” may represent a font collection.
If a font file contains multiple font, the font index can be used to specify which font to use. By default, the
font index is 0, which means the first font in the font file will be used.Font Size
The font size decides how big a font will appear in the image. The font size is expressed in a font unit called
points. This is the same unit used in common word processors.
Instead of specifying font size, some ChartDirector API (eg. TextBox.setFontSize) allow you to specify font
height and font width separately. You may use different point sizes for font height and font width to create
special effects.Font Color
This is the color to draw the font. (See Color Specification on how colors are represented in ChartDirector.)Font Angle
This is the angle in degrees by which the font should be rotated anti-clockwise.Vertical Layout
By default, text are laid out horizontally, with characters being drawn from left to right.
ChartDirector also supports vertical layout, with characters being drawn from top to bottom. For example,
you may use BaseChart.addText to add text that are laid out vertically. Vertical layout is common for
oriental languages such as Chinese, Japanese and Korean.
20.0.25
ChartDirector: Mark Up Language
Plugin Version: 8.2, Console & Web: No, Mac: Yes, Win: Yes, Linux: Yes. Answer: ChartDirector: Mark
Up Language
Notes:
ChartDirector Mark Up Language (CDML) is a language for including formatting information in text strings
by marking up the text with tags.
CDML allows a single text string to be rendered using multiple fonts, with different colors, and even embed
images in the text.Font Styles
You can change the style of the text by using CDML tags. For example, the line:
<*font=timesi.ttf,size=16,color=FF0000>Hello <*font=arial.ttf,size=12,color=8000*>world!
will result in the following text rendered:
In general, all tags in CDML are enclosed by <* and *>. Attributes within the tags determine the styles of
the text following the tags within the same block.
If you want to include <* in text without being interpreted as CDML tags, use <<* as the escape sequence.
496
CHAPTER 20. THE FAQ
The following table describes the supported font style attributes in CDML. See Font Specification for details
on various font attributes.
AttributeDescription
font
size
width
height
color
bgColor
underline
sub
super
Starts a new style section, and sets the font name. You may use this attribute
without a value (that is, use ”font” instead of ”font=arial.ttf”) to create a new
style section without modifying the font name.
The font size.
The font width. This attribute is used to set the font width and height to
different values. If the width and height are the same, use the size attribute.
The font height. This attribute is used to set the font width and height to
different values. If the width and height are the same, use the size attribute.
The text color in hex format.
The background color of the text in hex format.
The line width of the line used to underline the following characters. Set to 0
to disable underline.
Set the following text to be in subscript style. This attribute does not need to
have a value. (You may use ”sub” as the attribute instead of ”sub=1”.)
Set the following text to be in superscript style.
Set the following text to be in superscript style. This attribute does not need to have a value. (You may
use ”super” as the attribute instead of ”super=1”.)
xoffset
yoffset
advance
advanceTo
Draw the following the text by shifting the text horizontally from the original
position by the specified offset in pixels.
Draw the following the text by shifting the text vertically from the original
position by the specified offset in pixels.
Move the cursor forward (to the right) by the number of pixels as specified by
the value this attribute.
Move the cursor forward (to the right) to the position as specified by the value
this attribute. The position is specified as the number of pixels to the right
of the left border of the block. If the cursor has already passed through the
specified position, the cursor is not moved.
Note that unlike HTML tags, no double or single quotes are used in the tags. It is because CDML tags are
often embedded as string literals in source code. The double or single quotes, if used, will conflict with the
string literal quotes in the source code. Therefore in CDML, no quotes are necessary and they must not be
497
used.
Also, unlike HTML tags, CDML uses the comma character as the delimiter between attributes. It is because certain attributes may contain embed spaces (such as the font file name). So space is not used as the
delimiter and the comma character is used instead.
Note the font attribute above starts a new style section, while other attributes just modify the current style
section. You may use <*/font*>to terminate a style section, which will restore the font styles to the state
before the style section.Blocks and Lines
In CDML, a text string may contain multiple blocks. A block may contain multiple lines of text by separating them with new line characters (”\n”) or with <*br*>. The latter is useful for programming languages
that cannot represent new line characters easily.
For example, the line:
<*size=15*><*block*><*color=FF*>BLOCK<*br*>ONE<*/*>and <*block*><*color=FF00*>BLOCK<*br*>TWO<
will result in the following text rendered:
The above example contains a line of text. The line contains two blocks with the characters ” and ” in
between. Each block in turn contains two lines. The blocks are defined using <*block*>as the start tag and
<*/*>as the end tag.
When a block ends, font styles will be restored to the state before entering the block.Embedding Images
CDML supports embedding images in text using the following syntax:
<*img=my image file.png*>
where my image file.png is the path name of the image file.
For example, the line:
<*size=20*>A <*img=sun.png*>day
will result in the following text rendered:
ChartDirector will automatically detect the image file format using the file extension, which must either png,
jpg, jpeg, gif, wbmp or wmp (case insensitive).
Please refer to BaseChart.setSearchPath or DrawArea.setSearchPath on the directory that ChartDirector
will search for the file.
The <*img*>tag may optionally contain width and height attributes to specify its pixel width and height.
In this case, ChartDirector will stretch or compress the image if necessary to the required width and
498
CHAPTER 20. THE FAQ
height.Blocks Attributes
CDML supports nesting blocks, that is, a block can contain other sub-blocks. Attributes are supported in the
<*block*>tag to control the alignment and orientation of the sub-blocks. The <*img=my image file.png*>is
treated as a block for layout purposes.
For example, the line:
<*block,valign=absmiddle*><*img=molecule.png*><*block*>Hydrazino\nMolecule<*/*><*/*>
will result in the following text rendered:
The the above starts <*block,valign=absmiddle*>which specifies its content should align with each others
in the vertical direction using the absolute middle alignment. The block contains an image, followed by a
space characters, and then another block which has two lines of text.
The following table describes the supported attributes inside <*block*>tag:
AttributeDescription
width
height
maxwidth
truncate
linespacing
bgColor
valign
The width of the block in pixels. By default, the width is automatically determined to be the width necessary for the contents of the block. If the width
attribute is specified, it will be used as the width of the block. If the width is
insufficient for the contents, the contents will be wrapped into multiple lines.
The height of the block in pixels. By default, the height is automatically
determined to be the height necessary for the contents of the block. If the
height attribute is specified, it will be used as the height of the block.
The maximum width of the block in pixels. If the content is wider than maximum width, it will be wrapped into multiple lines.
The maximum number of lines of the block. If the content requires more than
the maximum number of lines, it will be truncated. In particular, if truncate is
1, the content will be truncated if it exceeds the maximum width (as specified
by maxwidth or width) without wrapping. The last few characters at the
truncation point will be replaced with ”...”.
The spacing between lines as a ratio to the default line spacing. For example,
a line spacing of 2 means the line spacing is two times the default line spacing.
The default line spacing is the line spacing as specified in the font used.
The background color of the block in hex format.
The vertical alignment of sub-blocks. This is for blocks that contain sub-blocks.
Supported values are baseline, top, bottom, middle and absmiddle.
The value baseline means the baseline of sub-blocks should align with the baseline of the block. The baseline
499
is the underline position of text. This is normal method of aligning text, and is the default in CDML. For
images or blocks that are rotated, the baseline is the same as the bottom.
The value top means the top line of sub-blocks should align with the top line of the block.
The value bottom means the bottom line of sub-blocks should align with the bottom line of the block.
The value middle means the middle line of sub-blocks should align with the the middle line of the block.
The middle line is the middle position between the top line and the baseline.
The value absmiddle means the absolute middle line of sub-blocks should align with the absolute middle line
of the block. The absolute middle line is the middle position between the top line and the bottom line.
halign
The horizontal alignment of lines. This is for blocks that contain multiple lines.
Supported values are left, center and right.
The value left means the left border of each line should align with the left border of the block. This is the
default.
The value center means the horizontal center of each line should align with the horizontal center of the block.
The value right means the right border of each line should align with the right border of the block.
angle
20.0.26
Rotate the content of the block by an angle. The angle is specified in degrees
in counter-clockwise direction.
ChartDirector: Parameter Substitution and Formatting
Plugin Version: 8.2, Console & Web: No, Mac: Yes, Win: Yes, Linux: Yes. Answer: ChartDirector:
Parameter Substitution and Formatting
Notes:
ChartDirector charts often contain a lot of text strings. For example, sector labels in pie charts, axis labels
for x and y axes, data labels for the data points, HTML image maps, etc, are all text strings.
ChartDirector uses parameter substitution to allow you to configure precisely the information contained in
the text and their format.
Format Strings
500
CHAPTER 20. THE FAQ
In parameter substitution, format strings are used to specify the entities to be include into labels and how
to format numbers and dates.
For example, when drawing a pie chart with side label layout, the default sector label format string is:
” { label } ( { percent } % )”
When the sector label is actually drawn, ChartDirector will replace ” { label } ” with the sector name, and
” { percent } ” with the sector percentage. So the above label format will result is a sector label similar to
”ABC (34.56% )”.
You may change the sector label format by changing the format string. For example, you may change it to:
” { label } : US$ { value | 2 } K ( { percent } % )”
The sector label will then become something like ”ABC: US$ 123.00 (34.56% )”.
In general, in ChartDirector parameter substitution, parameters enclosed by curly brackets will be substituted with their actual values when creating the texts.
For parameters that are numbers or dates/times, ChartDirector supports a special syntax in parameter
substitution to allow formatting for these values. Please refer to the Number Formatting and Date/Time
Formatting sections below for details.
Parameter Expressions
ChartDirector supports numeric expressions in format strings. They are denoted by enclosing the expression
with curly brackets and using ”=” as the first character. For example:
”USD { value } (Euro { = { value } *0.9 } )”
In the above, ” { value } ” will be substituted with the actual value of the sector. The expression ” { = {
value } *0.9 } ” will be substituted with the actual value of the sector multiplied by 0.9.
ChartDirector parameter expressions support operators ”+”, ”-”, ”*”, ”/”, ”% ” (modulo) and ”ˆ” (exponentiation). Operators ”*”, ”/”, ”% ”, ”ˆ” is computed first, followed by ”+” and ”-”. Operators of
the same precedence are computed from left to right). Parenthesis ”(” and ”)” can be used to change the
computation order.
Parameters for Pie Charts
The following table describes the parameters available for pie charts.
Parameters for All XY Chart Layers
The followings are parameters that are apply to all XY Chart layers in general. Some layer types may have
501
Parameter
sector
dataSet
label
dataSetName
value
percent
fieldN
Description
The sector number. The first sector is 0, while the nth sector is (n-1).
Same as { sector } . See above.
The text label of the sector.
Same as { label } . See above.
The data value of the sector.
The percentage value of the sector.
The (N + 1)th extra field. For example, { field0 } means the first extra field. An
extra field is an array of custom elements added using BaseChart.addExtraField
or BaseChart.addExtraField2.
additional parameters (see below).
Note that certain parameters are inapplicable in some context. For example, when specifying the aggregate
label of a stacked bar chart, the { dataSetName } parameter is inapplicable. It is because a stacked bar is
composed of multiple data sets. It does not belong to any particular data set and hence does not have a
data set name.
{ fieldN } means the extra field is indexed by the data point number. The Pth data point corresponds to
the Pth element of the extra field.
Additional Parameters for Line Layers
The followings are parameters that are in additional to the parameters for all XY Chart layers.
Additional Parameters for Trend Layers
The followings are parameters that are in additional to the parameters for all XY Chart layers.
Additional Parameters for Box-Whisker Layers
The followings are parameters that are in additional to the parameters for all XY Chart layers.
Additional Parameters for HLOC and CandleStick Layers
The followings are parameters that are in additional to the parameters for all XY Chart layers.
Additional Parameters for Vector Layers
The followings are parameters that are in additional to the parameters for all XY Chart layers.
Parameters for All Polar Layers
The followings are parameters that are apply to all Polar Chart layers in general. Some layer types may
have additional parameters (see below).
502
CHAPTER 20. THE FAQ
{ fieldN } means the extra field is indexed by the data point number. The Pth data point corresponds to
the Pth element of the extra field.
Additional Parameters for PolarVector Layers
The followings are parameters that are in additional to the parameters for all Polar Chart layers.
Parameters for Axis
The following table describes the parameters available for pie charts.
Number Formatting
For parameters that are numbers, ChartDirector supports a number of formatting options in parameter
substitution.
For example, if you want a numeric field { value } to have a precision of two digits to the right of the decimal
point, use ’,’ (comma) as the thousand separator, and use ’.’ (dot) as the decimal point, and you may use {
value | 2,. } . The number 123456.789 will then be displayed as 123,456.79.
For numbers, the formatting options are specified using the following syntax:
{ [ param ] | [ a ] [ b ] [ c ] [ d ] }
where:
If this field starts with ”E” or ”e”, followed by a number, it means formatting the value using scientific notation with the specified number of decimal places. If the ”E” or ”e” is not followed by a number, 3 is assumed.
For example, { value | E4 } will format the value 10.3 to 1.0300E+1, and { value | e4 } will format the same
value to 1.0300e+1.
If this field starts with ”G” or ”g”, followed by a number, it means formatting the value using the scientific
notation only if the value is large and requires more than the specified number of digits, or the value is
less than 0.001. If scientific notation is used, the number following ”G” or ”g” also specifies the number of
significant digits to use. If the ”G” or ”g” is not followed by a number, 4 is assumed.
For example, consider the format string { value | G4 } . The value 10 will be formatted to 10. The value
100000 will be formatted to 1.000E+5. Similarly, for { value | g4 } , the value 10 will be formatted to 10,
while the value 100000 will be formatted to 1.000e+5.
If you skip this argument, ChartDirector will display the exact value using at most 6 decimal places.
503
You may skip [ b ] [ c ] [ d ] . In this case, the default will be used.
Date/Time Formatting
For parameters that are dates/times, the formatting options can be specified using the following syntax:
{ [ param ] | [ datetime format string ] }
where [ datetime format string ] must start with an english character (A-Z or a-z) that is not ”G”, ”g”,
”E” or ”e”, and may contain any characters except ’ } ’. (If it starts with ”G”, ”g”, ”E” or ”e”, it will be
considered as a number format string.)
Certain characters are substituted according to the following table. Characters that are not substituted will
be copied to the output.
For example, a parameter substitution format of { value | mm-dd-yyyy } will display a date as something
similar to 09-15-2002. A format of { value | dd/mm/yy hh:nn:ss a } will display a date as something similar
to 15/09/02 03:04:05 pm.
If you want to include characters in the format string without substitution, you may enclose the characters
in single or double quotes.
For example, the format { value | mmm ’<*color=dd0000*>’yyyy } will display a date as something like
Jan <*color=dd0000*>2005 (the <*color=dd0000*>is a CDML tag to specify red text color). Note that
the <*color=dd0000*>tag is copied directly without substitution, even it contains ”dd” which normally will
be substituted with the day of month.
Escaping URL/HTML/CDML characters
Parameter substitution is often used to create HTML image maps. In HTML, some characters has special
meanings and cannot be used reliably. For example, the ’>’ is used to represent the end of an HTML tag.
Furthermore, if the field happens to be used as an URL, characters such as ’ ?’, ’& ’ and ’+’ also have special
meanings.
By default, ChartDirector will escape template fields used in URL and query parameters when generating
image maps. It will modify URL special characters to the URL escape format ”% XX” (eg. ”?” will become
”% 3F”). After that, it will modify HTML special characters to the HTML escape format ”& amps;# nn;”
(eg. ”>” will become ”& amps;# 62;”.). Similarly, it will escape other attributes in the image map using
HTML escape format (but not URL escape format).
In addition to escaping HTML and URL special characters, ChartDirector will also remove CDML fields in
creating image maps. It is because CDML is only interpreted in ChartDirector, should not be useful outside
of ChartDirector (such as in browser tool tips).
504
CHAPTER 20. THE FAQ
In some cases, you may not want ChartDirector to escape the special characters. For example, if the parameters have already been escaped before passing to ChartDirector, you may want to disable ChartDirector
from escaping them again.
ChartDirector supports the following special fields to control the escape methods - ” { escape url } ”, ” {
noescape url } ”, ” { escape html } ”, ” { noescape html } ”, ” { escape cdml } ” and { noescape cdml } ”.
These fields enable/disable the escape methods used in the template fields that follow them.
20.0.27
ChartDirector: Shape Specification
Plugin Version: 8.2, Console & Web: No, Mac: Yes, Win: Yes, Linux: Yes. Answer: ChartDirector: Shape
Specification
Notes:
Several ChartDirector API accept shape specification as arguments. For example, BarLayer.setBarShape
and BarLayer.setBarShape2 can be used to specify shapes of bars in bar charts, while DataSet.setDataSymbol, DataSet.setDataSymbol4, PolarLayer.setDataSymbol and PolarLayer.setDataSymbol4 can be used to
specify shapes for data symbols.
Note that in addition to shapes, in many cases ChartDirector also accepts images or custom draw objects for
data representation. For example, see DataSet.setDataSymbol2, DataSet.setDataSymbol3, PolarLayer.setDataSymbol2 and PolarLayer.setDataSymbol3.
Built-In Shapes
Built-in shapes are specified as integers. The integers can be explicit constants, or can be generated by a
ChartDirector method for parameterized shapes. For example, a circle is represented by an explicit constant
CircleShape (=7). On the other hand, the number representing a polygon depends on the number of sides
the polygon has, so it is generated by using the PolygonShape method, passing in the number of sides as
argument.
The following table illustrates the various ChartDirector shapes:
Custom Shapes
In ChartDirector, custom shapes are specified as an array of integers x0, y0, x1, y1, x2, y2 ... representing
the coordinates of the vertices of the custom polygonal shape.
The polygon should be defined with a bounding square of 1000 x 1000 units, in which the x-axis is from -500
to 500 going from left to right, and the y-axis is from 0 to 1000 going from bottom to top.
505
ChartDirector will automatically scale the polygon so that 1000 units will become to the pixel size as requested by the various ChartDirector API.
As an example, the shape of the standard diamond shape in ChartDirector is represented as an array with
8 numbers:
0, 0, 500, 500, 0, 1000, -500, 500
20.0.28
Copy styled text?
Plugin Version: all, Console & Web: No, Mac: Yes, Win: Yes, Linux: Yes. Answer: How to quickly copy
styled text from one textarea to another?
Example:
# if TargetWin32 then
TextArea1.WinRTFDataMBS = TextArea2.WinRTFDataMBS
# elseif TargetMacOS then
TextArea1.NSTextViewMBS.textStorage.setAttributedString TextArea2.NSTextViewMBS.textStorage
# else
TextArea1.StyledText = TextArea2.StyledText
# endif
Notes: The code above uses special plugin functions on Mac and Windows and falls back to framework for
Linux.
20.0.29
Do you have code to validate a credit card number?
Plugin Version: all, Console & Web: No, Mac: Yes, Win: Yes, Linux: Yes. Answer: You can check the
checksum to tell if a credit card number is not valid.
Example:
Dim
Dim
Dim
Dim
Dim
strNumber As String
nLength as Integer
nValue as Integer
nChecksum as Integer
nIndex as Integer
strNumber = EditField1.Text
nLength = Len(strNumber)
nChecksum = 0
For nIndex = 0 To nLength - 2
506
CHAPTER 20. THE FAQ
nValue = Val(Mid(strNumber, nLength - (nIndex + 1), 1)) * (2 - (nIndex Mod 2))
If nValue <10 Then
nChecksum = nChecksum + nValue
Else
nChecksum = nChecksum + (nValue - 9)
End If
Next
If Val(Mid(strNumber, Len(strNumber), 1)) = (10 - (nChecksum Mod 10)) Mod 10 Then
MsgBox(”The credit card number looks valid”)
Else
MsgBox(”The credit card number is invalid”)
End IF
Notes:
Here’s some code that will validate the checksum for a credit card. It works for Visa, MasterCard, American Express and Discover. Not sure about others, but I imagine they use the same basic algorithm. Of
course, this doesn’t actually mean that the credit card is valid, it’s only useful for helping the user catch typos.
The above code doesn’t have any error checking and it expects that the credit card number will be entered
without spaces, dashes or any other non-numeric characters. Addressing those issues will be an exercise left
to the reader. :)
(From Mike Stefanik)
20.0.30
Do you have plugins for X-Rite EyeOne, eXact or i1Pro?
Plugin Version: all, Console & Web: No. Answer: Our EyeOne plugin is available on request for licensees
of the X-Rite SDKs.
Notes:
Please first go to X-Rite and get a SDK license.
Than we can talk about the plugin.
20.0.31
Does SQL Plugin handle stored procedures with multiple result sets?
Plugin Version: all, Console & Web: No, Mac: Yes, Win: Yes, Linux: Yes. Answer: Yes, the plugin can
work with multiple recordsets.
Notes:
You need to use SQLCommandMBS class. When you get back results, you use FetchNext to walk over all
507
records in the first result set. Than you simply start again with FetchNext to get the second record set.
Even the RecordSet functions should work, just use them twice to get all records from both record sets.
20.0.32
Does the plugin home home?
Plugin Version: all, Console & Web: No, Mac: Yes, Win: No, Linux: No. Answer: Yes, we like to know
who is using the plugin, so the plugin may contact our server.
Example:
none.
Notes:
Please note that this does not affect your users as the plugin will only do this in the IDE and the relevant
plugin part is never included in your applications.
The plugin if used for some hours, does contact our server to provide statistical data about Xojo version and
OS versions. This way we know what versions are used. We can return the version number of the current
plugin which may be visible in future versions somehow. And we transmit partial licenses data so we can
track use of illegal license keys.
If you do not like to have this, you can block Xojo IDE from contacting our website via your Firewall.
Blocking the transfer will not disable the plugin or change the features.
Or contact us for a plugin version which explicitly does not contain this feature.
20.0.33
folderitem.absolutepath is limited to 255 chars. How can I get longer
ones?
Plugin Version: all, Console & Web: No, Mac: Yes, Win: Yes, Linux: Yes. Answer: Paths on a Mac are
not unique, so use them only to display them to the user.
Example:
Function AbsolutePath(f as FolderItem) As String
Dim s as string
Dim nf as FolderItem
nf = f
s = ””
while nf<>nil
s = nf.name + ”:” + s
nf = nf.parent
wend
Return s
508
CHAPTER 20. THE FAQ
End Function
20.0.34
Future of editablemovie class?
Plugin Version: all, Console & Web: No, Mac: Yes, Win: Yes, Linux: Yes. Answer: In short, it will go
away, so switch to plugin functions soon.
Notes:
The editableMovie class has been deprecated.
Deprecated means that Real Software will remove it someday, but as of today (and probably a few more
years) the class will be available and running. Just not forever. The reason is that Apple deprecated the old
QuickTime APIs and they are not available for 64 bit.
For 64 bit, you can move to our QTKit plugin.
We expect the old QuickTime classes in Real Studio and our plugins will continue to work in 32 bit applications. Even if editableMovie class is removed next year from Real Studio, our plugin still provides movie
class extensions to do similar functions.
20.0.35
Has anyone played round with using CoreImage to do things like add
dissolve transitions say when changing from one tab to another within
a window?
Console & Web: No, Mac: Yes, Win: No, Linux: No. Answer: This code implements animations for a
tabpanel change:
Example:
// in a tabpanel.change event:
dim r as CGSTransitionRequestMBS
dim co as new CGSConnectionMBS
dim cw as CGSWindowMBS
dim ct as CGSTransitionMBS
static OldTab as Integer
cw=co.CGSWindow(window1)
If cw = Nil Then
return // 10.3...
End If
r=new CGSTransitionRequestMBS
r.TransitionType=r.CGSFlip
r.HasBackGround=false
r.HasBackColor=false
r.Win=cw
// watch the value of the clicked tab versus the last tab
509
if tabpanel1.Value=0 or tabpanel1.Value <OldTab then
r.TransitionOption=r.CGSLeft
ct=co.NewTransition(r)
if ct<>Nil then
Refresh
ct.Invoke(1)
ct.Wait(1)
ct.Release
else
MsgBox ”Error creating the transition.”
end if
else
r.TransitionOption=r.CGSRight
ct=co.NewTransition(r)
if ct<>Nil then
Refresh
ct.Invoke(1)
ct.Wait(1)
ct.Release
else
MsgBox ”Error creating the transition.”
end if
end if
// Keep track of the last tab clicked
OldTab = tabpanel1.Value
Notes: See CGS* classes for more details.
20.0.36
How about Plugin support for older OS X?
Plugin Version: all, Console & Web: No, Mac: Yes, Win: Yes, Linux: Yes. Answer: We support in general
Mac OS X 10.5 and newer.
Notes:
All the 64-bit plugins on Mac require OS X 10.7.
Intel 32-bit plugins on Mac require OS X 10.5 or newer.
Currently the ChartDirector 6, GraphicsMagick and GameKit plugins requires Mac OS X 10.6.
Also for SQL Plugin the built in SQLite library requires 10.6.
510
20.0.37
CHAPTER 20. THE FAQ
How can I detect whether an Intel CPU is a 64bit CPU?
Plugin Version: all, Console & Web: No. Answer: Look on the CPU family returned by sysctl:
Example:
Function is64bit() As Boolean
# if TargetLittleEndian
dim m as MemoryBlock = NewMemoryBlock(8)
dim family as Integer
dim s as string
m=SystemControlNameToMIBMBS(”hw.cpufamily”)
m=SystemControlMBS(m)
if m<>nil then
m.LittleEndian=True
family=m.Long(0)
const CPUFAMILY INTEL 6 14 = & h73d67300 //* ”Intel Core Solo” and ”Intel Core Duo” (32-bit
Pentium-M with SSE3) */
const CPUFAMILY INTEL 6 15 = & h426f69ef //* ”Intel Core 2 Duo” */
const CPUFAMILY INTEL 6 23 = & h78ea4fbc //* Penryn */
const CPUFAMILY INTEL 6 26 = & h6b5a4cd2 //* Nehalem */
Select case family
case CPUFAMILY INTEL 6 14
Return false
case CPUFAMILY INTEL 6 15
Return true
case CPUFAMILY INTEL 6 23
Return true
case CPUFAMILY INTEL 6 26
Return true
// newer CPUs may be missing here
end Select
end if
# endif
Return false
Exception
Return false
End Function
511
Notes: This code is written for Mac OS X where you only have a limited number of possible CPUs.
20.0.38
How can I disable the close box of a window on Windows?
Plugin Version: all, Console & Web: No, Mac: No, Win: Yes, Linux: No. Answer: The following code will
remove the close item from the system menu of the window.
Example:
# if TargetWin32 then
Declare Function GetSystemMenu Lib ”user32” (hwnd as Integer, bRevert as Integer) as Integer
Declare Function RemoveMenu Lib ”user32” (hMenu as Integer, nPosition as Integer, wFlags as Integer) as
Integer
Dim hSysMenu as Integer
hSysMenu = GetSystemMenu(me.WinHWND, 0)
RemoveMenu hSysMenu, & HF060, & H0
# endif
Notes: The window may not be updated directly.
20.0.39
How can I get all the environment variables from Windows?
Plugin Version: all, Console & Web: No, Mac: No, Win: Yes, Linux: No. Answer: Try this code:
Example:
# if targetWin32
declare function GetEnvironmentStrings Lib ”kernel32” () as ptr
dim m as memoryBlock
dim n as Integer
m=GetEnvironmentStrings()
n=0
do
msgBox m.cstring(n)
while m.byte(n)<>0
n=n+1
wend
n=n+1
loop until m.byte(n)=0
# endif
512
CHAPTER 20. THE FAQ
Notes: The MBS Plugin has an EnvironmentMBS class for this.
20.0.40
How can i get similar behavior to Roxio Toast or iTunes where clicking
a ’burn’ button allows the next inserted blank CD-R to bypass the
Finder and be accepted by my application?
Plugin Version: all, Console & Web: No, Mac: Yes, Win: No, Linux: No. Answer: You need to get a
media reservation.
Example:
dim d as DRDeviceMBS // get a device
d.AcquireMediaReservation
Notes:
Use the plugin function AcquireMediaReservation and later release it using ReleaseMediaReservation.
See plugin examples on how to use it and check Apples DiscRecording framework documentation for more
details.
20.0.41
How can I get text from a PDF?
Plugin Version: all, Console & Web: No, Mac: Yes, Win: Yes, Linux: Yes. Answer: Crossplatform you
can use DynaPDF Pro.
Notes:
On Mac OS X you can also use PDFKit for the same job.
While DynaPDF Pro gives you each bit of text with rotation, font information and encoding details, PDFKit
gives you only the text string for a PDF page.
20.0.42
How can I get text from a Word Document?
Plugin Version: all, Console & Web: No, Mac: Yes, Win: Yes, Linux: Yes. Answer: to get the text string
from a doc file, use the NSAttributedStringMBS class.
Notes:
The NSAttributedStringMBS class is Mac OS X only and we have currently no solution for Windows or Linux.
Use the NSAttributedStringMBS.initWithDocFormat(data as string) as boolean method.
513
20.0.43
How can I get the item string for a given file creator?
Plugin Version: all, Console & Web: No. Answer: Try this function:
Example:
Sub pullNativeDocs(aCREA As string)
Dim result as Integer
Dim m, k as memoryBlock
Dim f as folderItem
Dim newType as string
Dim anIcon As picture
Dim ofs as Integer
Declare Function GetFileTypesThatAppCanNativelyOpen Lib ”Carbon” (appVRefNumHint as Short, appSignature as OSType, nativeTypes as Ptr) as Short Inline68K(”701CABFC”)
Declare Function GetDocumentKindString Lib ”Carbon” (docVRefNum as Short, docType as OSType, docCreator as OSType, kindString as ptr) as Short Inline68K(”7016ABFC”)
listBox1.deleteAllRows
m = newMemoryBlock(1024)
result = GetFileTypesThatAppCanNativelyOpen(Volume(0).MacVRefNum, aCREA, m)
if result <>0 then
listBox1.addRow ”<Not found.>”
return
end if
do
if m.byte(ofs*4) = 0 then
exit
else
newType = m.OSTypeMBS(ofs*4)
listBox1.addRow newType
k = newMemoryBlock(64)
result = GetDocumentKindString(Volume(0).MacVRefNum, newType, aCREA, k)
if result = 0 then
listBox1.cell(ofs,1) = k.pString(0)
ofs = ofs + 1
else
listBox1.cell(ofs,1) = ”(unknown)”
end if
end if
loop
End Sub
514
CHAPTER 20. THE FAQ
Notes: Change ”Translation” to ”CarbonLib” for Mac OS X.
20.0.44
How can I launch an app using it’s creator code?
Plugin Version: all, Console & Web: No, Mac: Yes, Win: No, Linux: No. Answer: Send an AppleEvent
”odoc” with the creator code to the Finder (”MACS”):
Example:
Function LaunchByCreator(C As String) As Boolean
Dim A As AppleEvent
A = NewAppleEvent(”aevt”,”odoc”,”MACS”)
A.ObjectSpecifierParam(”—-”) = GetUniqueIDObjectDescriptor(”appf”,nil,C)
return A.Send
End Function
20.0.45
How can I learn what shared libraries are required by a plugin on
Linux?
Plugin Version: all, Console & Web: No, Mac: Yes, Win: No, Linux: No. Answer: Please use the ldd
command in the terminal.
Notes:
You build an app on any platform, but for Linux.
For the resulting .so files in the libs folder, you can run the ldd command with the library path as parameter.
It shows you references lib files and you can make sure you have those installed.
This is a sample run of our graphicsmagick plugin:
[email protected]:
textasciitilde /MeinProgramm/MeinProgramm Libs$ ldd libMBSGraphicsMagickPlugin17744.so
linux-gate.so.1 =>(0xb76ee000)
libdl.so.2 =>/lib/i386-linux-gnu/libdl.so.2 (0xb6f0e000)
libgtk-x11-2.0.so.0 =>/usr/lib/i386-linux-gnu/libgtk-x11-2.0.so.0 (0xb6aa6000)
libpthread.so.0 =>/lib/i386-linux-gnu/libpthread.so.0 (0xb6a8a000)
libstdc++.so.6 =>/usr/lib/i386-linux-gnu/libstdc++.so.6 (0xb69a5000)
libm.so.6 =>/lib/i386-linux-gnu/libm.so.6 (0xb6979000)
libgcc s.so.1 =>/lib/i386-linux-gnu/libgcc s.so.1 (0xb695b000)
libc.so.6 =>/lib/i386-linux-gnu/libc.so.6 (0xb67b1000)
/lib/ld-linux.so.2 (0xb76ef000)
libgdk-x11-2.0.so.0 =>/usr/lib/i386-linux-gnu/libgdk-x11-2.0.so.0 (0xb6701000)
libpangocairo-1.0.so.0 =>/usr/lib/i386-linux-gnu/libpangocairo-1.0.so.0 (0xb66f4000)
libX11.so.6 =>/usr/lib/i386-linux-gnu/libX11.so.6 (0xb65c0000)
515
libXfixes.so.3 =>/usr/lib/i386-linux-gnu/libXfixes.so.3 (0xb65ba000)
libatk-1.0.so.0 =>/usr/lib/i386-linux-gnu/libatk-1.0.so.0 (0xb659a000)
libcairo.so.2 =>/usr/lib/i386-linux-gnu/libcairo.so.2 (0xb64ce000)
libgdk pixbuf-2.0.so.0 =>/usr/lib/i386-linux-gnu/libgdk pixbuf-2.0.so.0 (0xb64ad000)
libgio-2.0.so.0 =>/usr/lib/i386-linux-gnu/libgio-2.0.so.0 (0xb6356000)
libpangoft2-1.0.so.0 =>/usr/lib/i386-linux-gnu/libpangoft2-1.0.so.0 (0xb632a000)
libpango-1.0.so.0 =>/usr/lib/i386-linux-gnu/libpango-1.0.so.0 (0xb62e0000)
libfontconfig.so.1 =>/usr/lib/i386-linux-gnu/libfontconfig.so.1 (0xb62ab000)
libgobject-2.0.so.0 =>/usr/lib/i386-linux-gnu/libgobject-2.0.so.0 (0xb625c000)
libglib-2.0.so.0 =>/lib/i386-linux-gnu/libglib-2.0.so.0 (0xb6163000)
libXext.so.6 =>/usr/lib/i386-linux-gnu/libXext.so.6 (0xb6151000)
libXrender.so.1 =>/usr/lib/i386-linux-gnu/libXrender.so.1 (0xb6147000)
libXinerama.so.1 =>/usr/lib/i386-linux-gnu/libXinerama.so.1 (0xb6142000)
libXi.so.6 =>/usr/lib/i386-linux-gnu/libXi.so.6 (0xb6132000)
libXrandr.so.2 =>/usr/lib/i386-linux-gnu/libXrandr.so.2 (0xb6129000)
libXcursor.so.1 =>/usr/lib/i386-linux-gnu/libXcursor.so.1 (0xb611e000)
libXcomposite.so.1 =>/usr/lib/i386-linux-gnu/libXcomposite.so.1 (0xb611a000)
libXdamage.so.1 =>/usr/lib/i386-linux-gnu/libXdamage.so.1 (0xb6115000)
libfreetype.so.6 =>/usr/lib/i386-linux-gnu/libfreetype.so.6 (0xb607b000)
libxcb.so.1 =>/usr/lib/i386-linux-gnu/libxcb.so.1 (0xb605a000)
libpixman-1.so.0 =>/usr/lib/i386-linux-gnu/libpixman-1.so.0 (0xb5fc2000)
libpng12.so.0 =>/lib/i386-linux-gnu/libpng12.so.0 (0xb5f98000)
libxcb-shm.so.0 =>/usr/lib/i386-linux-gnu/libxcb-shm.so.0 (0xb5f93000)
libxcb-render.so.0 =>/usr/lib/i386-linux-gnu/libxcb-render.so.0 (0xb5f89000)
libz.so.1 =>/lib/i386-linux-gnu/libz.so.1 (0xb5f73000)
libgmodule-2.0.so.0 =>/usr/lib/i386-linux-gnu/libgmodule-2.0.so.0 (0xb5f6e000)
libselinux.so.1 =>/lib/i386-linux-gnu/libselinux.so.1 (0xb5f4f000)
libresolv.so.2 =>/lib/i386-linux-gnu/libresolv.so.2 (0xb5f36000)
libexpat.so.1 =>/lib/i386-linux-gnu/libexpat.so.1 (0xb5f0c000)
libffi.so.6 =>/usr/lib/i386-linux-gnu/libffi.so.6 (0xb5f05000)
libpcre.so.3 =>/lib/i386-linux-gnu/libpcre.so.3 (0xb5ec9000)
librt.so.1 =>/lib/i386-linux-gnu/librt.so.1 (0xb5ec0000)
libXau.so.6 =>/usr/lib/i386-linux-gnu/libXau.so.6 (0xb5ebb000)
libXdmcp.so.6 =>/usr/lib/i386-linux-gnu/libXdmcp.so.6 (0xb5eb4000)
[email protected]:
textasciitilde /MeinProgramm/MeinProgramm Libs$
As you see all library have been found and their load address is printed behind the na,e.
If a library is missing, you usually see the address missing there or being zero.
20.0.46
How can I validate an email address?
Plugin Version: all, Console & Web: No, Mac: Yes, Win: Yes, Linux: Yes. Answer: You can try this code:
Example:
516
CHAPTER 20. THE FAQ
Dim re As RegEx
re = New RegEx
Dim rm As RegExMatch
re.SearchPattern = ” [ a-z0-9!# $ % & ’*+/=?ˆ ’ { | }
textasciitilde - ] +(?:\. [ a-z0-9!# $ % & ’*+/=?ˆ ’ { | }
textasciitilde - ] +)*@(?: [ a-z0-9 ] (?: [ a-z0-9- ] * [ a-z0-9 ] )?\.)+ [ a-z0-9 ] (?: [ a-z0-9- ] * [ a-z0-9 ] )?”
rm = re.Search(editField1.Text)
if rm = Nil Then
StaticText2.text = editField1.Text + ” not valid email”
Else
StaticText2.Text = editField1.Text + ” is valid”
End if
Notes:
Adapted from:
http://www.regular-expressions.info/email.html
20.0.47
How do I check if the QuickTime component for the JPEG exporting
is available?
Plugin Version: all, Console & Web: No, Mac: Yes, Win: Yes, Linux: No. Answer: If you want to know if
the PictureToString functions will work, you may try this function:
Example:
Function IsQTJPEGExporerAvailable() As boolean
dim q as QTComponentInformationMBS
// search for QuickTime JPEG exporter codec
q=new QTComponentInformationMBS
while q.NextComponent
if q.Type=”imco” and q.SubType=”jpeg” then
Return true
end if
wend
Return false // not found
End Function
517
Notes:
It should work like this for other types like:
”tiff” ->TIFF
”PNTG” ->Mac Paint
”gif ” ->GIF
”WRLE” ->Windows BMP
”tga ” ->Targa
”png ” ->PNG
etc.
20.0.48
How do I check if the QuickTime component for the JPEG importing
is available?
Plugin Version: all, Console & Web: No, Mac: Yes, Win: Yes, Linux: No. Answer: If you want to know if
the StringToPicture functions will work, you may try this function:
Example:
Function IsQTJPEGImporterAvailable() As boolean
dim q as QTComponentInformationMBS
// search for QuickTime JPEG importer codec
q=new QTComponentInformationMBS
while q.NextComponent
if q.Type=”imdc” and q.SubType=”jpeg” then
Return true
end if
wend
Return false // not found
End Function
Notes:
It should work like this for other types like:
”tiff” ->TIFF
”PNTG” ->Mac Paint
”gif ” ->GIF
”WRLE” ->Windows BMP
”tga ” ->Targa
”png ” ->PNG
etc.
518
CHAPTER 20. THE FAQ
20.0.49
How do I check if the QuickTime component for the Sequence grabber
is available?
Plugin Version: all, Console & Web: No, Mac: Yes, Win: Yes, Linux: No. Answer: If you want to know if
the QTGrabberClass will work, you can use this code:
Example:
Function IsQTGrabberAvailable() As boolean
dim q as QTComponentInformationMBS
q=new QTComponentInformationMBS
while q.NextComponent
if q.Type=”barg” then
Return true
end if
wend
Return false // not found
End Function
Notes: Don’t forget that you need to check for each other component you use like the compression functions.
20.0.50
How do I decode correctly an email subject?
Plugin Version: all, Console & Web: No, Mac: Yes, Win: Yes, Linux: Yes. Answer: The following code
can be used to decode an email subject including several encodings including Base 64.
Example:
dim src as string // input
dim
dim
dim
dim
theRegex as Regex
theRegexMatch as RegexMatch
result, infoCharset, encodedPart as string
theStart as Integer
if instr(src, ”=?”) >0 then
theRegex = new Regex
theRegex.Options.Greedy = false
theRegex.searchPattern = ”(.*)=\?(.+)\?(Q | B)\?(.+)\?=”
theRegexMatch = theRegex.search(src)
while theRegexMatch <>nil
theStart = theRegexMatch.subExpressionStartB(0) + len(theRegexMatch.subExpressionString(0))
result = result + theRegexMatch.subExpressionString(1)
519
infoCharset = theRegexMatch.subExpressionString(2)
encodedPart = theRegexMatch.subExpressionString(4)
if theRegexMatch.subExpressionString(3) = ”B” then
encodedPart = DecodeBase64(encodedPart)
elseif theRegexMatch.subExpressionString(3) = ”Q” then
encodedPart = DecodeQuotedPrintable(encodedPart)
end if
if right(result, 1) = ” ” then
result = mid(result, 1, len(result)-1)
end if
encodedPart = encodedPart.DefineEncoding(GetInternetTextEncoding(infoCharset))
result = result + encodedPart
theRegex.SearchStartPosition = theStart
theRegexMatch = theRegex.search()
wend
result = result + mid(src, theStart+1)
else
result = src
end if
// theRegexMatch = theRegex.search
msgbox result
Notes: May not look nice depending on the controls used.
20.0.51
How do I enable/disable a single tab in a tabpanel?
Plugin Version: all, Console & Web: No, Mac: Yes, Win: No, Linux: No. Answer: Use the TabpanelEnabledMBS method.
Example:
TabpanelEnabledMBS(tabpanel1, 1, false)
Notes:
Use Carbon for MachO and CarbonLib for Mac Carbon and AppearanceLib for Mac OS Classic as library.
For Cocoa, please use enabled property of NSTabViewItemMBS class.
520
CHAPTER 20. THE FAQ
20.0.52
How do I find the root volume for a file?
Plugin Version: all, Console & Web: No, Mac: Yes, Win: Yes, Linux: Yes. Answer: Try this function:
Example:
Function GetRootVolume(f as FolderItem) as FolderItem
dim root, dum as folderItem
if f <>nil then
root = f // f might be the volume
do
dum = root.parent
if dum <>nil then
root = dum
end if
loop until dum = nil
return root
end if
End Function
20.0.53
How do I get the current languages list?
Plugin Version: all, Console & Web: No, Mac: Yes, Win: No, Linux: No. Answer: Try this code:
Example:
dim
dim
dim
dim
dim
p as new CFPreferencesMBS
a as CFArrayMBS
s as CFStringMBS
o as CFObjectMBS
sa(-1) as string
o=p.CopyAppValue(”AppleLanguages”,”.GlobalPreferences”)
if o<>Nil then
a=CFArrayMBS(o)
dim i,c as Integer
c=a.Count-1
for i=0 to c
o=a.Item(i)
if o isa CFStringMBS then
s=CFStringMBS(o)
sa.Append s.str
end if
521
next
end if
MsgBox Join(sa,EndOfLine)
Notes:
On Mac OS X you can get the list of current languages like this list:
de
en
ja
fr
es
it
pt
pt-PT
nl
sv
nb
da
fi
ru
pl
zh-Hans
zh-Hant
ko
Which has German (de) on the top for a German user.
This code has been tested on Mac OS X 10.5 only.
20.0.54
How do I get the Mac OS Version?
Plugin Version: all, Console & Web: No, Mac: Yes, Win: No, Linux: No. Answer: Try this code:
Example:
dim i as Integer
if system.gestalt(”sysv”, i) then
//do this in an ’If’ in case you don’t get any value back at all and system.gestalt returns boolean
if i = & h750 then //If OS is 7.5
//do stuff
elseif i = & h761 then //If OS is 7.6.1
//do stuff
end if
522
CHAPTER 20. THE FAQ
end if
Notes: The MBS Plugin has a function SystemInformationMBS.OSVersionString for this.
20.0.55
How do I get the printer name?
Plugin Version: all, Console & Web: No. Answer: For Mac OS Classic see the code below and for Mac OS
X use the Carbon Print Manager Classes from the MBS Plugin.
Example:
dim s as String
dim i as Integer
s=app.ResourceFork.GetResource(”STR ”,-8192)
if s<>”” then
i=ascb(leftb(s,1))
s=mid(s,2,i)
MsgBox s
end if
Notes:
A note from Craig Hoyt:
After looking at your example I had a little deja-vu experience. Several
years ago I played around with this same code if FutureBasic. I discovered
that it did not and still doesn’t provide the ’Printer Name’, it does
return the print driver name. If it returns ’LaserWriter 8’ as the print
driver you can look into this file and get the ’PAPA’ resource # -8192 to
get the actual Printer Name. Unfortunately this does not hold true for
other printers. My Epson and HP Printers (the Epson has an Ethernet Card
and the HP is USB) do not provide this info in their drivers. As far as I
can tell it only returns the name by polling the printer itself.
20.0.56
How do I make a metal window if RB does not allow me this?
Plugin Version: all, Console & Web: No, Mac: Yes, Win: No, Linux: No. Answer: The following declare
turns any window on Mac OS X 10.2 or newer into a metal one.
Example:
523
declare sub ChangeWindowAttributes lib ”Carbon” (win as windowptr, a as Integer, b as Integer)
ChangeWindowAttributes window1,256,0
Notes: May not look nice depending on the controls used.
20.0.57
How do I make a smooth color transition?
Plugin Version: all, Console & Web: No, Mac: Yes, Win: Yes, Linux: Yes. Answer:
I’d like to show in a report some bars, which start with color A
and end with color B.
The color change should be very smooth.
My problem: If I would start from 255,0,0 and end by 0,0,0, I would have
255 different colors. If the bars are longer than 255 pixels, would
this look nice?
Example:
// Window.Paint:
Sub Paint(g As Graphics)
dim w,w1,x,p as Integer
dim c1,c2,c as color
dim p1,p2 as Double
c1=rgb(255,0,0) // start color
c2=rgb(0,255,0) // end color
w=g.Width
w1=w-1
for x=0 to w1
p1=x/w1
p2=1.0-p1
c=rgb(c1.red*p1+c2.red*p2, c1.green*p1+c2.green*p2, c1.blue*p1+c2.blue*p2)
g.ForeColor=c
g.DrawLine x,0,x,g.Height
next
End Sub
524
CHAPTER 20. THE FAQ
Notes: Try the code above in a window paint event handler.
20.0.58
How do I read the applications in the dock app?
Plugin Version: all, Console & Web: No, Mac: Yes, Win: No, Linux: No. Answer: Use CFPreferencesMBS
class like in this example:
Example:
// Reads file names from persistent dock applications and puts them into the list
dim pref as new CFPreferencesMBS
dim
dim
dim
dim
persistentapps as CFStringMBS = NewCFStringMBS(”persistent-apps”)
ApplicationID as CFStringMBS = NewCFStringMBS(”com.apple.dock”)
tiledata as CFStringMBS = NewCFStringMBS(”tile-data”)
filelabel as CFStringMBS = NewCFStringMBS(”file-label”)
// get the array of persistent applications from dock preferences
dim o as CFObjectMBS = pref.CopyValue(persistentapps, ApplicationID, pref.kCFPreferencesCurrentUser,
pref.kCFPreferencesAnyHost)
if o isa CFArrayMBS then
dim a as CFArrayMBS = CFArrayMBS(o)
// walk over all items in array
dim c as Integer = a.Count-1
for i as Integer = 0 to c
// get dictionary describing item
o = a.Item(i)
if o isa CFDictionaryMBS then
dim d as CFDictionaryMBS = CFDictionaryMBS(o)
// and pick tile data dictionary
o = d.Value(tiledata)
if o isa CFDictionaryMBS then
d = CFDictionaryMBS(o)
// and pick there the file label
o = d.Value(filelabel)
if o isa CFStringMBS then
// and display it
dim name as string = CFStringMBS(o).str
List.AddRow name
525
end if
end if
end if
next
else
MsgBox ”Failed to read dock preferences.”
end if
Notes: You can use the CFPreferencesMBS.SetValue to change a value and CFPreferencesMBS.Synchronize
to write the values to disc. You may need to restart the Dock.app if you modified things.
20.0.59
How do I truncate a file?
Plugin Version: all, Console & Web: No, Mac: Yes, Win: Yes, Linux: Yes. Answer: In a binarystream you
can set the length property to truncate.
20.0.60
How do update a Finder’s windows after changing some files?
Plugin Version: all, Console & Web: No, Mac: Yes, Win: No, Linux: No. Answer: Try this code:
Example:
dim f as folderitem // some file
dim ae as appleevent
ae=newappleevent(”fndr”,”fupd”,”MACS”)
ae.folderitemparam(”—-”)=f
if not ae.send then
//something went wrong
end if
Notes: The folderitem.finderupdate from the MBS Plugin does something like this.
20.0.61
How to access a USB device directly?
Plugin Version: all, Console & Web: No, Mac: Yes, Win: Yes, Linux: Yes. Answer: First, it depends on
the device.
Notes:
526
CHAPTER 20. THE FAQ
Some devices can be talked directly from user mode code, but some require a kernel driver.
For some devices you can use plugins to access them like:
• Audio and Video sources using the QTGrabberClassMBS
• Mass storage devices using the folderitem class.
• Serial devices using the System.SerialPort function.
• HID USB devices can be used with MacHIDMBS, WinHIDMBS or LinuxHIDInterface class.
• Any USB device may be used with MacUSBMBS or WinUSBMBS classes.
In general it is always the best to take the most high level access to have others do the work for the details.
20.0.62
How to add icon to file on Mac?
Plugin Version: all, Console & Web: No, Mac: Yes, Win: Yes, Linux: Yes. Answer: You can use
Folderitem.AddCustomIcon or NSWorkspaceMBS.setIcon functions.
Notes: Please close any open stream for the file you want to add an icon.
20.0.63
How to ask the Mac for the Name of the Machine?
Plugin Version: all, Console & Web: No, Mac: Yes, Win: No, Linux: No. Answer: Using Apple Events
you can use this code:
Example:
Function Computername() As string
dim theEvent as AppleEvent
dim err as boolean
theEvent = newAppleEvent(”mchn”,”getd”,”MACS”)
err = theEvent.send
return theevent.ReplyString
End Function
Notes:
527
Code above is for Mac OS 9!
Also the MBS Plugin has a function for this which may be faster and work also on Macs without Filesharing
(which handles this event).
20.0.64
How to automatically enable retina in my apps?
Plugin Version: all, Console & Web: No, Mac: Yes, Win: No, Linux: No. Answer: You can run a build
script on each build with this code:
Example:
Dim App As String = CurrentBuildLocation + ”/” + CurrentBuildAppName + ”.app”
Call DoShellCommand(”/usr/bin/defaults write ” + App + ”/Contents/Info ””NSHighResolutionCapable””
YES”)
Notes: This will set the NSHighResolutionCapable flag to YES.
20.0.65
How to avoid leaks with Cocoa functions?
Plugin Version: all, Console & Web: No, Mac: Yes, Win: No, Linux: No. Answer: You can try this code
on Mac OS X:
Example:
// in a Timer Action event:
Sub Action()
static LastPool as NSAutoreleasePoolMBS = nil
static CurrentPool as NSAutoreleasePoolMBS = nil
LastPool = CurrentPool
CurrentPool = new NSAutoreleasePoolMBS
End Sub
Notes:
With REALbasic 2009r4 the code above should not be needed as REALbasic runtime does automatically
handle the NSAutoreleasePools for you. For older REALbasic versions you need to use code with a timer
with the action event above to avoid memory leaks.
Please do not use REALbasic 2009r4 and newer with plugins before version 9.5. You can get crashes there
which typically show a line with a objc msgSend call.
528
20.0.66
CHAPTER 20. THE FAQ
How to avoid trouble connecting to oracle database with SQL Plugin?
Plugin Version: all, Console & Web: No, Mac: Yes, Win: No, Linux: No. Answer: For oracle the most
important thing is to point the plugin to the libraries from oracle.
Notes:
In environment variables, the paths like ORACLE HOME must be defined.
On Mac OS X you also need to define DYLD LIBRARY PATH to point to the dylib files from oracle.
For that you need to modify /etc/launchd.conf for Mac OS X 10.8 and newer.
In older versions those variables in .MacOSX/environment.plist file in user’s home.
Another way for the case you bundle things inside your app is to use the LSEnvironment key in info.plist.
In info.plist it looks like this:
<key>LSEnvironment</key>
<dict>
<key>test</key>
<string>Hello World</string>
</dict>
20.0.67
How to avoid
NSAutoreleaseNoPool console messages in threads?
Plugin Version: all, Console & Web: No, Mac: Yes, Win: No, Linux: No. Answer: You need to use your
own NSAutoreleasePool on a thread like this:
Example:
sub MyThread.run
dim pool as new NSAutoreleasePoolMBS
// do work here
pool=nil
end sub
Notes:
For more details read here:
http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Classes/NSAutoreleasePool Class/Reference/Reference.html
529
20.0.68
How to bring app to front?
Plugin Version: all, Console & Web: No, Mac: Yes, Win: Yes, Linux: Yes. Answer: On Mac you can use
this code:
Example:
// First way:
app.FrontMostMBS = true
// second way:
dim p as new ProcessMBS
p.GetCurrentProcess
p.FrontProcess = true
// third way:
NSApplicationMBS.sharedApplication.activateIgnoringOtherApps(true)
// for Windows:
RemoteControlMBS.WinBringWindowToTop
Notes: This will bring a Mac app to the front layer.
20.0.69
How to bring my application to front?
Plugin Version: all, Console & Web: No, Mac: Yes, Win: No, Linux: No. Answer: This makes SimpleText
(Code ttxt) to the frontmost application:
Example:
Dim A As AppleEvent
A = NewAppleEvent(”misc”,”actv”,””)
If Not A.Send then
Beep
end if
Notes: (Code is Mac only)
20.0.70
How to catch Control-C on Mac or Linux in a console app?
Plugin Version: all, Console & Web: No, Mac: Yes, Win: Yes, Linux: Yes. Answer: You can use
SignalHandlerMBS class for this.
Example:
530
CHAPTER 20. THE FAQ
// watch for Control-C on Mac
call SignalHandlerMBS.SetFlagHandler(2)
dim ende as boolean = false
do
if SignalHandlerMBS.IsFlagSet(2) then
Print ”Flag 2 set. Existing...”
ende = true
end if
DoEvents 1
loop until ende
Notes: The signal is catched, a flag is set and you can ask later in your normal application flow for the result.
20.0.71
How to change name of application menu?
Plugin Version: all, Console & Web: No, Mac: Yes, Win: Yes, Linux: No. Answer: Use this code to change
the application menu name on Mac OS X:
Example:
dim mb as new MenubarMBS
dim m as MenuMBS = mb.item(1) // 1 is in my tests the app menu
if m<>Nil then
m.MenuTitle = ”Hello World”
end if
Notes: This code is for Carbon only.
20.0.72
How to change the name in the menubar of my app on Mac OS X?
Plugin Version: all, Console & Web: No, Mac: Yes, Win: No, Linux: No. Answer:
You mean it screws up if the file name of the bundle itself is different
than the name of the executable file in the MacOS folder within the
bundle? If so, you should find something like this within your
Info.plist file (or the ’plst’ resource that the RB IDE builds for you):
<key>CFBundleExecutable</key>
<string>Executable file name here</string>
531
Just make sure that file name matches.
However, if your question involves how you can change the name of the app
that appears in the menu and the dock, that’s different. You can make
this name different from the file name by changing the CFBundleName key:
<key>CFBundleName</key>
<string>Name for menu here</string>
Note that if you use my free AppBundler program, this second part is
taken care of for you – just fill in a custom name in the right field.
You can find AppBundler (from Thomas Reed) at
http://www.bitjuggler.com/products/appbundler/ .
20.0.73
How to check if a folder/directory has subfolders?
Plugin Version: all, Console & Web: No, Mac: Yes, Win: Yes, Linux: Yes. Answer: You can use code like
this to check all items in a folder:
Example:
Function HasSubFolder(folder as FolderItem) As Boolean
dim c as Integer = folder.Count
for i as Integer = 1 to c
dim item as FolderItem = folder.TrueItem(i)
if item<>Nil and item.Directory then
Return true
end if
next
End Function
Notes:
We use trueitem() here to avoid resolving alias/link files.
Also we check for nil as we may not have permission to see all items.
And if one is a directory, we return without checking the rest.
532
20.0.74
CHAPTER 20. THE FAQ
How to check if Macbook runs on battery or AC power?
Plugin Version: all, Console & Web: No, Mac: Yes, Win: No, Linux: No. Answer: Please use our
IOPowerSourcesMBS class like this:
Example:
Function PowerSourceState() as Integer
dim p as new IOPowerSourcesMBS
// check all power sources
dim u as Integer = p.Count-1
for i as Integer = 0 to u
dim d as CFDictionaryMBS = p.Item(i)
if d<>nil then
// check if they have a power source state key:
dim o as CFObjectMBS = d.Value(NewCFStringMBS(”Power Source State”))
if o isa CFStringMBS then
dim s as string = CFStringMBS(o).str
’MsgBox s
if s = ”AC Power” then
Return 1
elseif s = ”Battery Power” then
Return 2
end if
end if
end if
next
Return 0 // unknown
End Function
Notes: If you want to check the CFDictionaryMBS content, simply use a line like ”dim x as dictionary =
d.dictionary” and check the contents in the debugger.
20.0.75
How to check if Microsoft Outlook is installed?
Plugin Version: all, Console & Web: No, Mac: Yes, Win: Yes, Linux: Yes. Answer: If you need Outlook
for Scripting, you should simply check registry for the required Outlook.Application class:
Example:
Function OutlookInstalled() As Boolean
# if TargetWin32 then
try
533
dim r as new RegistryItem(”HKEY CLASSES ROOT\Outlook.Application\CLSID”, false)
Return true
catch r as RegistryAccessErrorException
// not installed
Return false
end try
# else
// Windows only, so false on other platforms
Return false
# endif
End Function
20.0.76
How to check on Mac OS which country or language is currently selected?
Plugin Version: all, Console & Web: No, Mac: Yes, Win: No, Linux: No. Answer: The code below returns
a country value.
Example:
dim result as Integer
IF TargetMacOS THEN
CONST smScriptLang = 28
CONST smSystemScript = -1
DECLARE FUNCTION GetScriptManagerVariable LIB ”Carbon” ( selector as Integer) as Integer
DECLARE FUNCTION GetScriptVariable LIB ”Carbon” ( script as Integer, selector as Integer) as Integer
result=GetScriptVariable(smSystemScript, smScriptLang)
END IF
Notes:
Returns values like:
534
CHAPTER 20. THE FAQ
For more values, check ”Script.h” in the frameworks.
20.0.77
How to code sign my app with plugins?
Plugin Version: all, Console & Web: No, Mac: Yes, Win: No, Linux: No. Answer: When you try to code
sign the application with plugin dylibs on Mac OS X, you may see error message that there is actually a
signature included.
Notes:
Please use the -f command line parameter with codesign utility to overwrite our MBS signature.
We sign our plugins for Mac and Windows to make sure they have not been modified.
In terminal, you do like this:
cd <Path to folder of app>
codesign -f -s ”Developer ID Application: <Your Name>” ”<Appname>.app/Contents/Frameworks/*.dylib”
codesign -f -s ”Developer ID Application: <Your Name>” ”<Appname>.app/Contents/Frameworks/*.framework”
codesign -f -s ”Developer ID Application: <Your Name>” ”<Appname>.app”
Please use the name of your certificate (See keychain), the name of your app and the path to the app folder.
If you have helper apps you need to sign them first.
You can use a build step to automatically sign your app on build.
20.0.78
How to collapse a window?
Plugin Version: all, Console & Web: No, Mac: Yes, Win: No, Linux: No. Answer: Use this function (Mac
only):
Example:
Sub CollapseRBwindow(w as window, CollapseStatus as boolean)
dim state, err as Integer
dim wh as MemoryBlock
Declare Function CollapseWindow Lib ”Carbon” (window as Integer,collapse as Integer) as Integer
IF CollapseStatus THEN
state = 1
ELSE
state = 0
END IF
535
err = CollapseWindow(w.MacWindowPtr, state)
End Sub
Notes:
Also the MBS Plugin has a window.collapsedmbs property you can set.
For Windows the MBS Plugin has a window.isiconicmbs property.
20.0.79
How to compare two pictures?
Plugin Version: all, Console & Web: No, Mac: Yes, Win: Yes, Linux: Yes. Answer: You can try this code:
Example:
Function ComparePictures(p as picture,q as picture) as Integer
dim r,u as RGBSurface
dim x,y,n,m,h,w as Integer
dim w1,w2,h1,h2,d1,d2 as Integer
dim c1,c2 as color
h1=p.Height
h2=q.Height
w1=p.Width
w2=q.Width
d1=p.Depth
d2=q.Depth
if d1<>d2 then
Return 1
elseif w1<>w2 then
return 2
elseif h1<>h2 then
Return 3
else
r=p.RGBSurface
u=q.RGBSurface
if r=nil or u=nil then
Return -1
else
h=h1-1
w=w1-1
m=min(w,h)
536
CHAPTER 20. THE FAQ
for n=0 to m
c1=r.Pixel(n,n)
c2=u.Pixel(n,n)
if c1<>c2 then
Return 4
end if
next
for y=0 to h
for x=0 to w
c1=r.Pixel(x,y)
c2=u.Pixel(x,y)
if c1<>c2 then
Return 5
end if
next
next
// 0 for equal
// -1 for error (no RGBsurface)
// 1 for different depth
// 2 for different width
// 3 for different height
// 4 for different pixels (fast test)
// 5 for different pixels (slow test)
end if
end if
Exception
Return -1
End Function
Notes: Remember that this only works on bitmap pictures, so the picture.BitmapMBS function may be
useful.
20.0.80
How to compile PHP library?
Plugin Version: all, Console & Web: No, Mac: Yes, Win: No, Linux: No. Answer: You have to download
the source code and compile a static version of the library.
Notes:
This instructions were written based on PHP 5.2.6 on Mac OS X:
• Best take a new Mac with current Xcode version installed.
537
• Download the source code archive. e.g. ”php-5.2.6.tar.bz2”
• Expand that archive on your harddisc.
• Open terminal window
• change directory to the php directory. e.g. ”cd /php-5.2.6”
• execute this two lines to define the supported CPU types and the minimum Mac OS X version:
• export CFLAGS=”-arch ppc -arch i386 -mmacosx-version-min=10.3”
• export CXXFLAGS=”-arch ppc -arch i386 -mmacosx-version-min=10.3”
• the command ”./configure help” does show the configure options.
• use configure with a line like this:
• ./configure –enable-embed –with-curl -enable-ftp –enable-zip –enable-sockets –enable-static –enable-soap
–with-zlib –with-bz2 –enable-exif –enable-bcmath –enable-calendar
• start the compilation with ”make all”
• other option is to use ”make install” which first does the same as ”make all” and than does some
installation scripts.
• you may get an error about a duplicate symbole yytext. Search the file ”zend ini scanner.c”, search
a line with ”char *yytext;” and change it to ”extern char *yytext;”.
• On the end you get a lot of error messages, but you have a working library (named libphp5.so) file in
the invisible ”.libs” folder inside your php source folder.
Possible problems and solutions:
• If the path to your files has spaces, you can get into trouble. e.g. ”/RB Plugins/PHP” is bad as files
will be searched sometimes in ”/RB”.
• If you have in /usr/local/lib libraries which conflict with the default libraries, you can get into trouble.
• If you installed some open source tools which compiled their own libraries, you can get into conflicts.
• if you have to reconfigure or after a problem, you may need to use ”make clean” before you start ”make
all” again.
Feel free to install additional libraries and add more packages to the configure line.
538
20.0.81
CHAPTER 20. THE FAQ
How to convert a BrowserType to a String with WebSession.Browser?
Plugin Version: all, Console & Web: No, Mac: Yes, Win: Yes, Linux: Yes. Answer: Use code like this:
Example:
Function GetBrowserName(s as WebSession.BrowserType) As string
Select case s
case WebSession.BrowserType.Android
Return ”Andriod”
case WebSession.BrowserType.Blackberry
Return ”Blackberry”
case WebSession.BrowserType.Chrome
Return ”Chrome”
case WebSession.BrowserType.ChromeOS
Return ”ChromeOS”
case WebSession.BrowserType.Firefox
Return ”Firefox”
case WebSession.BrowserType.InternetExplorer
Return ”InternetExplorer”
case WebSession.BrowserType.Opera
Return ”Opera”
case WebSession.BrowserType.Safari
Return ”Safari”
case WebSession.BrowserType.SafariMobile
Return ”SafariMobile”
case WebSession.BrowserType.Unknown
Return ”Unknown”
else
Return ”Unkown: ”+str(integer(s))
end Select
End Function
20.0.82
How to convert a EngineType to a String with WebSession.Engine?
Plugin Version: all, Console & Web: No, Mac: Yes, Win: Yes, Linux: Yes. Answer: Use code like this:
Example:
Function GetRenderingEngineName(s as WebSession.EngineType) As string
Select case s
case WebSession.EngineType.Gecko
Return ”Gecko”
case WebSession.EngineType.Presto
Return ”Presto”
case WebSession.EngineType.Trident
539
Return ”Trident”
case WebSession.EngineType.Unknown
Return ”Unknown”
case WebSession.EngineType.WebKit
Return ”WebKit”
else
Return ”Unkown: ”+str(integer(s))
end Select
End Function
20.0.83
How to convert a PlatformType to a String with WebSession.Platform?
Plugin Version: all, Console & Web: No, Mac: Yes, Win: Yes, Linux: Yes. Answer: Use code like this:
Example:
Function GetPlatformName(s as WebSession.PlatformType) As string
Select case s
case WebSession.PlatformType.Blackberry
Return ”Blackberry”
case WebSession.PlatformType.iPad
Return ”iPad”
case WebSession.PlatformType.iPhone
Return ”iPhone”
case WebSession.PlatformType.iPodTouch
Return ”iPodTouch”
case WebSession.PlatformType.Linux
Return ”Linux”
case WebSession.PlatformType.Macintosh
Return ”Macintosh”
case WebSession.PlatformType.PS3
Return ”PS3”
case WebSession.PlatformType.Unknown
Return ”Unknown”
case WebSession.PlatformType.WebOS
Return ”WebOS”
case WebSession.PlatformType.Wii
Return ”Wii”
case WebSession.PlatformType.Windows
Return ”Windows”
else
Return ”Unkown: ”+str(integer(s))
end Select
End Function
540
20.0.84
CHAPTER 20. THE FAQ
How to convert a text to iso-8859-1 using the TextEncoder?
Plugin Version: all, Console & Web: No, Mac: Yes, Win: Yes, Linux: Yes. Answer:
This code can help you althrough it’s not perfect.
You need to set lc to the current color you use.
Example:
dim outstring as string
dim theMac, thePC as textencoding
dim Mac2PC as textconverter
theMac = getTextEncoding(0) // MacRoman
thePC = getTextEncoding(& h0201) // ISOLatin1
Mac2PC = getTextConverter(theMac, thePC)
// if you wanted to do the opposite just create a converter
// PC2Mac = getTextConverter(thePC, theMac)
outstring = Mac2PC.convert(”Bjrn, this text should be converted”)
Mac2PC.clear
Notes: You have to call Mac2PC.clear after every conversion to reset the encoding engine.
20.0.85
How to convert ChartTime back to Xojo date?
Plugin Version: all, Console & Web: No, Mac: Yes, Win: Yes, Linux: Yes. Answer: We have this example
code:
Example:
Function ChartTimeToDate(ChartTime as Double) As date
static diff as Double = 0.0
if diff = 0.0 then
dim d2 as Double = CDBaseChartMBS.chartTime(2015, 1, 1)
dim da as new date(2015, 1, 1)
dim ts as Double = da.TotalSeconds
diff = ts - d2
end if
541
dim d as new date
d.TotalSeconds = diff + ChartTime
Return d
End Function
Notes: As you see we calculate the difference in base date from Date and ChartTime and later use difference
to convert.
20.0.86
How to convert line endings in text files?
Plugin Version: all, Console & Web: No, Mac: Yes, Win: No, Linux: No. Answer: You can simply read
file with TextInputStream and write with new line endings using TextOutputStream class.
Example:
dim
dim
dim
dim
inputfile as FolderItem = SpecialFolder.Desktop.Child(”test.txt”)
outputfile as FolderItem = SpecialFolder.Desktop.Child(”output.txt”)
it as TextInputStream = TextInputStream.Open(inputfile)
ot as TextOutputStream = TextOutputStream.Create(outputfile)
ot.Delimiter = EndOfLine.Windows // new line ending
while not it.EOF
ot.WriteLine it.ReadLine
wend
Notes: TextInputStream will read any input line endings and with delimiter property in TextOutputStream
you can easily define your new delimiter.
20.0.87
How to convert picture to string and back?
Plugin Version: all, Console & Web: No, Mac: Yes, Win: Yes, Linux: Yes. Answer: Use this plugin
functions:
Notes:
JPEG:
JPEGStringToPictureMBS(buf as string) as picture
JPEGStringToPictureMBS(buf as string,allowdamaged as Boolean) as picture
PictureToJPEGStringMBS(pic as picture,quality as Integer) as string
542
CHAPTER 20. THE FAQ
PNG:
PictureToPNGStringMBS(pic as picture, gamma as single) as string
PictureToPNGStringMBS(pic as picture, mask as picture, gamma as single) as string
PictureToPNGStringMBS(pic as picture, gamma as single, Interlace as Boolean, FilterType as Integer) as
string
PictureToPNGStringMBS(pic as picture, mask as picture, gamma as single, Interlace as Boolean, FilterType
as Integer) as string
PNGStringToPictureMBS(data as string, gamma as single) as picture
PNGStringToPNGPictureMBS(data as string, gamma as single) as PNGpictureMBS
Tiff:
TIFFStringToPictureMBS(data as string) as picture
TIFFStringToTiffPictureMBS(data as string) as TiffPictureMBS
BMP:
BMPStringtoPictureMBS(data as string) as picture
Picture.BMPDataMBS(ResolutionValueDPI as Integer=72) as string
GIF:
GifStringToGifMBS(data as string) as GIFMBS
GifStringToPictureMBS(data as string) as Picture
20.0.88
How to copy an array?
Plugin Version: all, Console & Web: No, Mac: Yes, Win: No, Linux: No. Answer: You can use a function
like this to copy an array:
Example:
Function CopyArray(a() as Double) as Double()
dim r() as Double
for each v as Double in a
r.Append v
next
Return r
End Function
543
Notes:
If needed make several copies of this method with different data types, not just double.
For a deep copy of an array of objects, you need to change code to also make a copy of those objects.
20.0.89
How to copy an dictionary?
Plugin Version: all, Console & Web: No, Mac: Yes, Win: No, Linux: No. Answer: You can use a function
like this to copy a dictionary:
Example:
Function CopyDictionary(d as Dictionary) As Dictionary
dim r as new Dictionary
for each key as Variant in d.keys
r.Value(key) = d.Value(key)
next
Return r
End Function
Notes:
If needed make several copies of this method with different data types, not just double.
For a deep copy of an dictionary of objects, you need to change code to also make a copy of those objects.
20.0.90
How to copy parts of a movie to another one?
Plugin Version: all, Console & Web: No, Mac: Yes, Win: Yes, Linux: No. Answer: The code below copies
ten seconds of the snowman movie to the dummy movie starting at the 5th second.
Example:
dim f as FolderItem
dim md as EditableMovie
dim ms as EditableMovie
f=SpecialFolder.Desktop.Child(”Our First Snowman.mov”)
ms=f.OpenEditableMovie
ms.SelectionStartMBS=5
ms.SelectionLengthMBS=10
f=SpecialFolder.Desktop.Child(”dummy.mov”)
md=f.CreateMovie
msgbox str(md.AddMovieSelectionMBS(ms))
544
CHAPTER 20. THE FAQ
Notes: If result is not 0, the method fails.
20.0.91
How to create a birthday like calendar event?
Plugin Version: all, Console & Web: No, Mac: Yes, Win: No, Linux: No. Answer: Try this code:
Example:
// start a connection to the calendar database
dim s as new CalCalendarStoreMBS
// needed for the error details
dim e as NSErrorMBS
dim r as CalRecurrenceRuleMBS = CalRecurrenceRuleMBS.initYearlyRecurrence(1, nil) // repeat every
year without end
dim a as new CalAlarmMBS // add alarm
a.action = a.CalAlarmActionDisplay
a.relativeTrigger = -3600*24 // 24 Hours before
// create a new calendar
dim c as new CalEventMBS
dim d as new date(2011, 04, 20) // the date
dim calendars() as CalCalendarMBS = s.calendars
// set properties
c.Title=”Test Birthday”
c.startDate=d
c.recurrenceRule = r
c.calendar=calendars(0) // add to first calendar
c.addAlarm(a)
c.endDate = d
c.isAllDay = true
// save event
call s.saveEvent(c,s.CalSpanAllEvents, e)
if e<>nil then
MsgBox e.localizedDescription
else
MsgBox ”New event was created.”
end if
545
Notes: This adds an event to iCal for the given date with alarm to remember you and repeats it every year.
20.0.92
How to create a GUID?
Plugin Version: all, Console & Web: No, Mac: Yes, Win: Yes, Linux: Yes. Answer: Use the UUIDMBS
class for this.
20.0.93
How to create a Mac picture clip file?
Plugin Version: all, Console & Web: No, Mac: No, Win: Yes, Linux: No. Answer: You can use code like
this one.
Example:
dim f As FolderItem
dim p As Picture
f=SpecialFolder.Desktop.Child(”Test.pictClipping”)
if f=nil then Return
p=new Picture(300,200,32) ’Make a sample picture
p.Graphics.ForeColor=RGB(0,255,255)
p.Graphics.FillOval 0,0,99,99
p.Graphics.ForeColor=RGB(255,0,0)
p.Graphics.DrawOval 0,0,99,99
dim r As ResourceFork ’ResourceFork is needed for a clip file
// Please define a file type Any
r=f.CreateResourceFork(”Any”)
// get PICT data using plugin function
dim pictdata as string = p.PicHandleDataMBS
r.AddResource(pictdata,”PICT”,256,”Picture”)
dim m as new MemoryBlock(8)
m.LittleEndian = false
m.Int16Value(0) = 0
m.Int16Value(2) = 0
m.Int16Value(4) = p.Width
m.Int16Value(6) = p.Height
546
CHAPTER 20. THE FAQ
r.AddResource(m,”RECT”,256,””)
’Values taken from a sample file and irrelevant to the problem
dim data as string = DecodeBase64(”AQAAAAAAAAAAAAAAAAACAFRDRVIAAAABAAAAAAAAAABUQ0lQAAAAA
r.AddResource(data,”drag”,128,””) ’ditto
r.Close
Notes: In general Apple has deprecated this, but a few application still support clippings.
20.0.94
How to create a PDF file in REALbasic?
Plugin Version: all, Console & Web: No, Mac: Yes, Win: Yes, Linux: Yes. Answer: Check our DynaPDF
plugin and the examples.
Notes:
An alternative can be to use the CoreGraphics and Cocoa functions on Mac OS X.
For Windows, we can only suggest our DynaPDF plugin.
20.0.95
How to create EmailAttachment for PDF Data in memory?
Plugin Version: all, Console & Web: No, Mac: Yes, Win: No, Linux: No. Answer: You can use code like
the one below:
Example:
Function EmailAttachmentFromPDFData(PDFData as string, filename as string) As EmailAttachment
dim a as new EmailAttachment
a.data = EncodeBase64(PDFData, 76)
a.ContentEncoding = ”base64”
a.MIMEType = ”application/pdf”
a.MacType = ”PDF ”
a.MacCreator = ”prvw”
a.Name = filename
Return a
End Function
Notes:
Compared to sample code from Xojo documentation, we set the mime type correct for PDF.
The MacType/MacCreator codes are deprecated, but you can still include them for older Mac email clients.
”prvw” is the creator code for Apple’s preview app.
547
20.0.96
How to create PDF for image files?
Plugin Version: all, Console & Web: No, Mac: Yes, Win: Yes, Linux: Yes. Answer: You can use DynaPDF
like this:
Example:
Function CreatePrintPDF(jpgFiles() as folderitem, pdfFile as FolderItem, PageWidth as Integer, PageHeight
as Integer) As Boolean
// have files?
If pdfFile = Nil Then Return False
If jpgFiles = Nil Then Return False
If jpgFiles.Ubound <0 Then Return False
// new DynaPDF
Dim pdf As New MyDynapdfMBS
// page width/height in MilliMeter
Dim pdfWidth as Integer = PageWidth * 72 / 25.4
Dim pdfHeight as Integer = PageHeight * 72 / 25.4
// put your license here
Call pdf.SetLicenseKey ”Starter”
// create pdf
Call pdf.CreateNewPDF pdfFile
// set a couple of options
Call pdf.SetPageCoords(MyDynaPDFMBS.kpcTopDown)
Call pdf.SetResolution(300)
Call pdf.SetUseTransparency(False)
Call pdf.SetSaveNewImageFormat(False)
Call pdf.SetGStateFlags(MyDynaPDFMBS.kgfUseImageColorSpace, False)
Call pdf.SetJPEGQuality(100)
// set page size
Call pdf.SetBBox(MyDynaPDFMBS.kpbMediaBox, 0, 0, pdfWidth, pdfHeight)
Call pdf.SetPageWidth(pdfWidth)
Call pdf.SetPageHeight(pdfHeight)
// append pages with one image per page
For i as Integer = 0 To jpgFiles.Ubound
Call pdf.Append
Call pdf.InsertImageEx(0, 0, pdfWidth, pdfHeight, jpgFiles(i), 1)
Call pdf.EndPage
548
CHAPTER 20. THE FAQ
Next
// close
Call pdf.CloseFile
Return True
End Function
Notes:
This is to join image files in paper size to a new PDF.
e.g. scans in A4 into an A4 PDF.
20.0.97
How to CURL Options translate to Plugin Calls?
Plugin Version: all, Console & Web: No, Mac: Yes, Win: Yes, Linux: Yes. Answer: Below a few tips on
how to translate command line CURL calls to plugin calls.
Notes:
curl -vX PUT http://localhost:5984/appserials/78569238475/DocumentRegister.docx?rev=3-25634563456
–data-binary @DocumentRegister.docx -H ”Content-Type: application/msword”
• The option -v means verbose. You can use OptionVerbose and listen for messages in the DebugMessage
event.
• The option -X PUT means we want to do a HTTP PUT Request. So set OptionPut to true. Also you
will want to set OptionUpload to true as you upload data.
• We have the URL which you put into OptionURL property.
• The –data-binary option tells CURL to pass the given data. With the @ before the data, it is intrepreted
as a file name, so the data is read from the given file. You’ll need to open this file and pass data with
the Read event as needed. (See CURLS ftp file upload example project)
• The last option -H specifies an additional header for the upload. Pas this additional header with the
SetOptionHTTPHeader method.
curl -X PUT http://127.0.0.1:5984/appserials/f2f4e540bf8bb60f61cfcd4328001c59 -d ’ { ”type”:”Product”,”description”:”Application Serial”,”acronym”:”AppSerial”,”dateAdded”:”2011-03-21 14:57:36” } ’
• Option -X PUT like above.
• Pass the URL again in OptionURL
• This time data is passed in command line for CURL. You’d put this data in the quotes into a string
and make it available in the Read event. (See CURLS ftp upload example project)
549
20.0.98
How to delete file with ftp and curl plugin?
Plugin Version: all, Console & Web: No, Mac: Yes, Win: Yes, Linux: Yes. Answer: You can set post/pre
quotes to have ftp commands executed before or after the download/upload.
Example:
dim d as CURLMBS // your curl object
// delete file
dim ws() As String
ws.Append ”DELE Temp.txt”
d.SetOptionPostQuote(ws)
Notes:
Use SetOptionPostQuote, SetOptionPreQuote or SetOptionQuote.
The ftp commands you pass here are native ftp commands and not the commands you use with ftp applications. To delete use DELE and the file path.
20.0.99
How to detect display resolution changed?
Plugin Version: all, Console & Web: No, Mac: Yes, Win: Yes, Linux: Yes. Answer: On Mac OS X simply
listen for display changed notifications.
Notes: Use the ”Distribution Notification Center.rbp” example project as a base and use it to listen to
notifications with the name ”O3DeviceChanged”.
20.0.100
How to detect retina?
Plugin Version: all, Console & Web: No, Mac: Yes, Win: Yes, Linux: Yes. Answer: Please use Window.BackingScaleFactorMBS to query the factor.
Example:
msgbox str(window1.BackingScaleFactorMBS)
20.0.101
How to disable force quit?
Plugin Version: all, Console & Web: No, Mac: Yes, Win: No, Linux: No. Answer:
Please visit this website and get the control panel for Mac OS 9 there:
http://www3.sk.sympatico.ca/tinyjohn/DFQ.html
550
CHAPTER 20. THE FAQ
For Mac OS X use the MBS Plugin with the SetSystemUIModeMBS method.
Notes: Please use presentationOptions in NSApplicationMBS for Cocoa applications.
20.0.102
How to disable the error dialogs from Internet Explorer on javascript
errors?
Plugin Version: all, Console & Web: No, Mac: No, Win: Yes, Linux: No. Answer: You can use this code
in the htmlviewer open event:
Example:
if targetwin32 then
htmlviewer1. ole.Content.value(”Silent”) = True
end if
Notes: This disables the error dialogs from Internet Explorer.
20.0.103
How to display a PDF file in REALbasic?
Plugin Version: all, Console & Web: No, Mac: Yes, Win: Yes, Linux: Yes. Answer: On Mac OS X you
can use CoreGraphics or PDFKit to display a PDF.
Notes:
An alternative can be to load the PDF into a htmlviewer so the PDF plugin can display it.
On Windows you may need to use the Acrobat ActiveX control from Adobe or launch Acrobat Reader.
20.0.104
How to do a lottery in RB?
Plugin Version: all, Console & Web: No, Mac: Yes, Win: Yes, Linux: Yes. Answer: Try this function:
Example:
Sub Lotto(max as Integer,count as Integer,z() as Integer)
// Lotto count numbers of max put into the array z beginning at index 0
dim n(0) as Integer ’ all the numbers
dim m as Integer ’ the highest field in the current array
dim i,a,b,d as Integer ’ working variables
’fill the array with the numbers
m=max-1
redim n(m)
551
for i=0 to m
n(i)=i+1
next
’ unsort them by exchanging random ones
m=max*10
for i=1 to m
a=rnd*max
b=rnd*max
d=n(a)
n(a)=n(b)
n(b)=d
next
’ get the first count to the dest array
m=count-1
redim z(m)
for i=0 to m
z(i)=n(i)
next
’sort the result
z.sort
End Sub
Sub Open()
// Test it
dim za(0) as Integer ’ the array of the numbers
lotto 49,6,za ’ 6 of 49 in Germany
’ and display them
staticText1.text=str(za(0))+chr(13)+str(za(1))+chr(13)+str(za(2))+chr(13)+str(za(3))+chr(13)+str(za(4))+chr(13)+str(za
End Sub
20.0.105
How to do an asycron DNS lookup?
Plugin Version: all, Console & Web: No, Mac: No, Win: Yes, Linux: No. Answer: use CFHostMBS class
(Mac OS X only).
Notes:
REALbasic internal functions and plugin DNS functions are sycronized.
552
CHAPTER 20. THE FAQ
You can use DNSLookupThreadMBS class for doing them asyncron.
20.0.106
How to draw a dushed pattern line?
Plugin Version: all, Console & Web: No, Mac: Yes, Win: Yes, Linux: Yes. Answer: You can try this code:
Example:
// call like this: DrawDushedPatternLine g,0,0,width,height,10
Sub DrawDushedPatternLine(g as graphics,x1 as Integer,y1 as Integer,x2 as Integer,y2 as Integer, partlen
as Integer)
dim x,y,ox,oy as Double
dim dx,dy as Double
dim w,h,d as Double
dim b as Boolean
w=x2-x1
h=y2-y1
d=sqrt(w*w+h*h)
dx=w/d*partlen
dy=h/d*partlen
b=true
x=x1
while (x<x2) and (y<y2)
ox=x
oy=y
x=x+dx
y=y+dy
if b then
g.DrawLine ox,oy,x,y
end if
b=not b
wend
End Sub
Notes: It would be possible to add this to the plugin, but I think it’s better if you do it in plain Realbasic
code, so it even works on Windows.
553
20.0.107
How to draw a nice antialiased line?
Plugin Version: all, Console & Web: No, Mac: Yes, Win: Yes, Linux: Yes. Answer:
This code can help you althrough it’s not perfect.
You need to set lc to the current color you use.
Example:
Sub drawLine(xs as Integer, ys as Integer, xe as Integer, ye as Integer, face as RGBSurface, lineColor as
color)
dim intX, intY, count, n, xDiff, yDiff as Integer
dim v, v1, floatX, floatY, xx, yy, xStep, yStep as Double
dim c as color
const st=1.0
xDiff=xe-xs
yDiff=ye-ys
count=max(abs(xDiff), abs(yDiff))
xStep=xDiff/count
yStep=yDiff/count
xx=xs
yy=ys
for n=1 to count
intX=xx
intY=yy
floatX=xx-intX
floatY=yy-intY
v=(1-floatX)*(1-floatY)*st
v1=1-v
c=face.pixel(intX, intY)
face.pixel(intX, intY)=rgb(v*lineColor.red+v1*c.red, v*lineColor.green+v1*c.green, v*lineColor.blue+v1*c.blue)
v=floatX*(1-floatY)*st
v1=1-v
c=face.pixel(intX+1, intY)
face.pixel(intX+1, intY)=rgb(v*lineColor.red+v1*c.red, v*lineColor.green+v1*c.green, v*lineColor.blue+v1*c.blue)
v=(1-floatX)*floatY*st
v1=1-v
c=face.pixel(intX, intY+1)
face.pixel(intX, intY+1)=rgb(v*lineColor.red+v1*c.red, v*lineColor.green+v1*c.green, v*lineColor.blue+v1*c.blue)
v=floatX*floatY*st
v1=1-v
c=face.pixel(intX+1, intY+1)
face.pixel(intX+1, intY+1)=rgb(v*lineColor.red+v1*c.red, v*lineColor.green+v1*c.green, v*lineColor.blue+v1*c.blue)
554
CHAPTER 20. THE FAQ
xx=xx+xStep
yy=yy+yStep
next
End Sub
Notes: PS: st should be 1 and face should be a RGBSurface or a Graphics object.
20.0.108
How to draw with CGContextMBS using my own handle?
Plugin Version: all, Console & Web: No, Mac: Yes, Win: Yes, Linux: Yes. Answer: You can try this code:
Example:
Soft Declare Function QDBeginCGContext Lib ”Carbon” (port as Integer, ByRef contextHandle as Integer)
as Integer
dim contextRef as Integer
call QDBeginCGContext(g.handle(graphics.HandleTypeCGrafPtr), contextRef)
dim c as new CGContextMBS(contextRef)
c.BeginPath
c.SetLineWidth(3)
c.SetRGBFillColor(1,0,0,0.5)
c.FillRect(CGMakeRectMBS(0,0,100,100))
c.DrawPath(c.kCGPathFillStroke)
c.Flush // and so on
Soft Declare Function QDEndCGContext Lib ”Carbon” (port as Integer, ByRef contextHandle as Integer) as Integer
dim h as Integer = c.Handle
call QDEndCGContext(g.handle(graphics.HandleTypeCGrafPtr), h)
c.Handle=0
Notes: Basicly you can provide your own handle to CGContextMBS. But if you do not set it back to 0 the
CGContextMBS destructor will release the handle which can result into a crash. (if the reference count is
wrong)
20.0.109
How to dump java class interface?
Plugin Version: all, Console & Web: No, Mac: Yes, Win: Yes, Linux: Yes. Answer: In terminal you can
use ”javap -s <classname>” to display the class with the method names and parameters.
Notes: For example show ResultSet class: javap -s java.sql.ResultSet
555
20.0.110
How to duplicate a picture with mask or alpha channel?
Plugin Version: all, Console & Web: No, Mac: Yes, Win: Yes, Linux: Yes. Answer: You can use code like
this function:
Example:
Function Duplicate(extends p as Picture) As Picture
# if RBVersion >= 2011.04 then
if p.HasAlphaChannel then
// create nw picture and copy content:
dim q as new Picture(p.Width, p.Height)
q.Graphics.DrawPicture p,0,0
Return q
end if
# endif
// create new picture
dim q as new Picture(p.Width, p.Height, 32)
// get mask
dim oldMask as Picture = p.mask(false)
if oldMask = nil then
// no mask, so simple copy
q.Graphics.DrawPicture p,0,0
Return q
end if
// remove mask
p.mask = nil
// copy picture and mask
q.Graphics.DrawPicture p, 0, 0
q.mask.Graphics.DrawPicture oldMask,0,0
// restore mask
p.mask = oldmask
Return q
End Function
Notes:
556
CHAPTER 20. THE FAQ
Simply copy it to a module and call it like this: q = p.duplicate.
The code above works with old Real Studio versions because of the # if even if your RS version does not
support alpha channel pictures. This way it’s future proof.
20.0.111
How to enable assistive devices?
Plugin Version: all, Console & Web: No, Mac: Yes, Win: No, Linux: No. Answer: You can use AppleScript
code like below:
Notes:
tell application ”System Events”
activate
set UI elements enabled to true
return UI elements enabled
end tell
You can run this with AppleScriptMBS class.
20.0.112
How to encrypt a file with Blowfish?
Plugin Version: all, Console & Web: No, Mac: Yes, Win: Yes, Linux: Yes. Answer: You can use code like
this:
Example:
dim fi as FolderItem = SpecialFolder.Desktop.Child(”test.xojo binary project”)
dim fo as FolderItem = SpecialFolder.Desktop.Child(”test.encrypted”)
// read input
dim bi as BinaryStream = BinaryStream.Open(fi)
dim si as string = bi.Read(bi.Length)
bi.Close
// encrypt
dim so as string = BlowfishMBS.Encrypt(”MyKey”,si)
// write output
dim bo as BinaryStream = BinaryStream.Create(fo)
bo.Write so
bo.Close
557
Notes: Of course you can decrypt same way, just use Decrypt function and of course swap files.
20.0.113
How to extract text from HTML?
Plugin Version: all, Console & Web: No, Mac: Yes, Win: Yes, Linux: Yes. Answer: Use both RemoveHTMLTagsMBS and DecodingFromHTMLMBS like this:
Example:
dim html as string = ”<p><B>Gr& uuml;& szlig;e</B></P>”
dim htmltext as string = RemoveHTMLTagsMBS(html)
dim text as string = DecodingFromHTMLMBS(htmltext)
MsgBox text // shows: Gre
Notes:
You can use it together with RemoveHTMLTagsMBS to remove html tags. What you get will be the text
without tags.
DecodingFromHTMLMBS turns HTML escapes back to unicode characters. Like & auml; to .
20.0.114
How to find empty folders in a folder?
Plugin Version: all, Console & Web: No, Mac: Yes, Win: Yes, Linux: Yes. Answer: Try this code:
Example:
dim folder as folderitem // your folder
dim c as Integer = folder.count
for i as Integer = 1 to c
dim item as folderitem = folder.trueitem(i)
if item = nil then
// ignore
elseif item.directory then
// folder
if item.count = 0 then
// found empty folder
end if
end if
next
558
20.0.115
CHAPTER 20. THE FAQ
How to find iTunes on a Mac OS X machine fast?
Plugin Version: all, Console & Web: No, Mac: Yes, Win: No, Linux: No. Answer: You can try Launch
Services.
Example:
dim f as FolderItem
f=LaunchServicesFindApplicationForInfoMBS(”hook”,”com.apple.iTunes”,”iTunes.app”)
MsgBox f.AbsolutePath
20.0.116
How to find network interface for a socket by it’s name?
Plugin Version: all, Console & Web: No, Mac: Yes, Win: No, Linux: No. Answer: You can use our plugin
to build a lookup table.
Example:
Function FindNetworkInterface(name as string) As NetworkInterface
name = name.trim
if name.len = 0 then Return nil
// search by IP/MAC
dim u as Integer = System.NetworkInterfaceCount-1
for i as Integer = 0 to u
dim n as NetworkInterface = System.GetNetworkInterface(i)
if n.IPAddress = name or n.MACAddress = name then
Return n
end if
next
// use MBS Plugin to build a mapping
dim interfaces() as NetworkInterfaceMBS = NetworkInterfaceMBS.AllInterfaces
dim map as new Dictionary
for each n as NetworkInterfaceMBS in interfaces
dim IPv4s() as string = n.IPv4s
dim IPv6s() as string = n.IPv6s
for each IPv4 as string in IPv4s
map.Value(IPv4) = n.Name
next
for each IPv6 as string in IPv6s
map.Value(IPv6) = n.Name
559
next
if n.MAC<>”” then
map.Value(n.MAC) = n.Name
end if
next
// now search interfaces by name, IPv4 or IPv6
for i as Integer = 0 to u
dim n as NetworkInterface = System.GetNetworkInterface(i)
if map.Lookup(n.IPAddress, ””) = name then
Return n
end if
if map.Lookup(n.MACAddress, ””) = name then
Return n
end if
next
End Function
Notes: The code above uses a lookup table build using NetworkInterfaceMBS class to find the network
interface by name.
20.0.117
How to find version of Microsoft Word?
Plugin Version: all, Console & Web: No, Mac: Yes, Win: Yes, Linux: Yes. Answer: You can use code like
this:
Example:
// find Word
dim f as FolderItem = LaunchServicesFindApplicationForInfoMBS(””,”com.microsoft.Word”,””)
// open bundle
dim c as new NSBundleMBS(f)
// read info
dim d as Dictionary = c.infoDictionary
// show version
MsgBox d.Lookup(”CFBundleVersion”,””)
Notes: Older versions of Word can be found with creator code ”MSWD”.
560
20.0.118
CHAPTER 20. THE FAQ
How to fix CURL error 60/53 on connecting to server?
Plugin Version: all, Console & Web: No, Mac: Yes, Win: No, Linux: No. Answer: You probably connect
with SSL and you have no valid certificate.
Example:
dim d as new CURLSMBS
// Disable SSL verification
d.OptionSSLVerifyHost = 0 // don’t verify server
d.OptionSSLVerifyPeer = 0 // don’t proofs certificate is authentic
// With SSL Verification:
dim cacert as FolderItem = Getfolderitem(”cacert.pem”)
d.OptionCAInfo = cacert.UnixpathMBS
d.OptionSSLVerifyHost = 2 // verify server
d.OptionSSLVerifyPeer = 1 // proofs certificate is authentic
Notes:
You can either use the code above to disable the SSL verification and have no security.
Or you use the cacert file and enable the verification. Than you only get a connection if the server has a
valid certificate.
see also:
http://curl.haxx.se/ca/
20.0.119
How to format double with n digits?
Plugin Version: all, Console & Web: No, Mac: Yes, Win: No, Linux: No. Answer: You can use the
FormatMBS function for this.
Example:
dim d as Double = 123.4567890
listbox1.AddRow FormatMBS(”% f”, d)
listbox1.AddRow FormatMBS(”% e”, d)
listbox1.AddRow FormatMBS(”% g”, d)
listbox1.AddRow FormatMBS(”% 5.5f”, d)
listbox1.AddRow FormatMBS(”% 5.5e”, d)
listbox1.AddRow FormatMBS(”% 5.5g”, d)
d = 0.000000123456
listbox1.AddRow FormatMBS(”% f”, d)
listbox1.AddRow FormatMBS(”% e”, d)
561
listbox1.AddRow FormatMBS(”% g”, d)
listbox1.AddRow FormatMBS(”% 5.5f”, d)
listbox1.AddRow FormatMBS(”% 5.5e”, d)
listbox1.AddRow FormatMBS(”% 5.5g”, d)
Notes:
see FormatMBS for details.
In general % f is normal style, % e is scientific and % g is whichever gives best result for given space.
20.0.120
How to get a time converted to user time zone in a web app?
Plugin Version: all, Console & Web: No, Mac: Yes, Win: Yes, Linux: Yes. Answer: Use the WebSession.GMTOffset property.
Example:
Sub Open()
// current date on server
dim d as new date
dim s as string = d.LongTime
// adjust to client GMT offset
d.GMTOffset = d.GMTOffset + Session.GMTOffset
dim t as string = D.LongTime
MsgBox s+EndOfLine+t
End Sub
20.0.121
How to get an handle to the frontmost window on Windows?
Plugin Version: all, Console & Web: No, Mac: No, Win: Yes, Linux: No. Answer: This function returns a
handle for the frontmost window:
Example:
Function GetForegroundWindowHandle() as Integer
# if targetwin32 then
declare function GetForegroundWindow Lib ”user32.dll” as Integer
Return GetForegroundWindow()
# endif
End Function
562
20.0.122
CHAPTER 20. THE FAQ
How to get CFAbsoluteTime from date?
Plugin Version: all, Console & Web: No, Mac: Yes, Win: Yes, Linux: No. Answer: Use code like this:
Example:
dim d as new date
dim t as CFTimeZoneMBS = SystemCFTimeZoneMBS
dim g as new CFGregorianDateMBS
g.Day = d.Day
g.Month = d.Month
g.Year = d.Year
g.Minute = d.Minute
g.Hour = d.Hour
g.Second = d.Second
dim at as CFAbsoluteTimeMBS = g.AbsoluteTime(t)
dim x as Double = at.Value
MsgBox str(x)
Notes:
As you see we need a timezone and put the date values in a gregorian date record.
Now we can query absolute time for the given timezone.
20.0.123
How to get client IP address on web app?
Plugin Version: all, Console & Web: No, Mac: Yes, Win: Yes, Linux: Yes. Answer: Use the WebSession.RemoteAddress property.
Example:
Sub Open()
Title = Session.RemoteAddress
End Sub
563
20.0.124
How to get fonts to load in charts on Linux?
Plugin Version: all, Console & Web: No, Mac: Yes, Win: Yes, Linux: Yes. Answer: Please use the
SetFontSearchPath method in the CDBaseChartMBS class to specify where your fonts are.
Example:
if TargetLinux then
CDBaseChartMBS.SetFontSearchPath ”/usr/share/fonts/truetype”
else
// on Mac and Windows we use system fonts.
end if
Notes:
On Mac OS X and Windows, the fonts are loaded from the system’s font folder.
e.g. if you use ubuntu, you can install the ttf-mscorefonts-installer package and call this method with
”/usr/share/fonts/truetype/msttcorefonts” as the path. No backslash on the end of a path, please.
20.0.125
How to get fonts to load in DynaPDF on Linux?
Plugin Version: all, Console & Web: No, Mac: Yes, Win: Yes, Linux: Yes. Answer: Please use the
AddFontSearchPath method in the DynaPDFMBS class to specify where your fonts are.
Example:
dim d as new DynaPDFMBS
if TargetLinux then
call d.AddFontSearchPath ”/usr/share/fonts/truetype”, true
else
// on Mac and Windows we use system fonts.
end if
Notes:
On Mac OS X and Windows, the fonts are loaded from the system’s font folder.
e.g. if you use ubuntu, you can install the ttf-mscorefonts-installer package and call this method with
”/usr/share/fonts/truetype/msttcorefonts” as the path. No backslash on the end of a path, please.
564
20.0.126
CHAPTER 20. THE FAQ
How to get GMT time and back?
Plugin Version: all, Console & Web: No, Mac: Yes, Win: No, Linux: No. Answer: You can use the date
class and the GMTOffset property.
Example:
// now
dim d as new date
// now in GMT
dim e as new date
e.GMTOffset = 0
// show
MsgBox str(d.TotalSeconds,”0.0”)+” ”+str(e.TotalSeconds, ”0.0”)
dim GMTTimeStamp as Double = e.TotalSeconds
// restore
dim f as new date
// add GMT offset here
f.TotalSeconds = GMTTimeStamp + f.GMTOffset*3600
// because here it’s removed
f.GMTOffset = f.GMTOffset
MsgBox d.ShortTime+” (”+str(d.GMTOffset)+”) ”+str(d.TotalSeconds,”0.0”)+EndOfLine+
e.ShortTime+” (”+str(e.GMTOffset)+”) ”+str(e.TotalSeconds,”0.0”)+EndOfLine+
f.ShortTime+” (”+str(f.GMTOffset)+”) ”+str(f.TotalSeconds,”0.0”)
Notes: It’s sometimes a bit tricky with the date class as setting one property often changes the others.
20.0.127
How to get good crash reports?
Plugin Version: all, Console & Web: No, Mac: Yes, Win: Yes, Linux: Yes. Answer: Check this website
from the webkit website:
Notes: http://webkit.org/quality/crashlogs.html
20.0.128
How to get list of all threads?
Plugin Version: all, Console & Web: No, Mac: Yes, Win: Yes, Linux: Yes. Answer: You can use the
runtime module like in this function:
565
Example:
Function Threads() As Thread()
# pragma DisableBackgroundTasks
dim t() as Thread
Dim o as Runtime.ObjectIterator=Runtime.IterateObjects
While o.MoveNext
if o.Current isa Thread then
t.Append thread(o.current)
end if
Wend
Return t
End Function
Notes:
This returns an array of all thread objects currently in memory.
The pragma is important here as it avoids thread switches which may cause a thread to be created or deleted.
20.0.129
How to get parameters from webpage URL in Real Studio Web Edition?
Plugin Version: all, Console & Web: No, Mac: Yes, Win: Yes, Linux: Yes. Answer: Use the Webpage.ParametersReceived event.
Example:
Sub ParametersReceived(Variables As Dictionary)
for each key as Variant in Variables.keys
MsgBox key+” ->”+Variables.Value(key)
next
End Sub
Notes: The text encodings of this strings is not defined in Real Studio 2010r5. Please use DefineEncoding.
20.0.130
How to get Real Studio apps running Linux?
Plugin Version: all, Console & Web: No, Mac: Yes, Win: Yes, Linux: Yes. Answer: You need to install
some requuire packages.
Notes:
566
CHAPTER 20. THE FAQ
You need CUPS as well as GTK packages. On 64 bit systems also the ia32-libs package.
Please note that you need a x86 compatible Linux. So no PPC, Power, ARM or other CPUs.
20.0.131
How to get the color for disabled textcolor?
Plugin Version: all, Console & Web: No, Mac: Yes, Win: No, Linux: No. Answer: Ask the appearance
manager:
Example:
Function GetThemeTextColor(inColor as Integer, inDepth as Integer, inColorDev as Boolean) As Color
declare function GetThemeTextColor lib ”Carbon” (inColor as Integer, inDepth as Integer, inColorDev as
Boolean, outColor as Ptr) as Integer
dim i as Integer
dim col as MemoryBlock
col = newMemoryBlock(6)
i = GetThemeTextColor(inColor, inDepth, inColorDev, col)
return RGB(col.UShort(0)\256, col.UShort(2)\256, col.UShort(4)\256)
End Function
Notes:
The color for this is:
const kThemeTextColorDialogInactive = 2.
c = GetThemeTextColor(kThemeTextColorDialogInactive, Screen(0).Depth, true)
For Mac OS X you should use ”CarbonLib” instead of ”AppearanceLib” ...
20.0.132
How to get the current free stack space?
Plugin Version: all, Console & Web: No, Mac: Yes, Win: No, Linux: No. Answer: You can something like
the code below:
Example:
567
Sub ShowStackSize()
dim threadid as Integer
dim size as Integer
declare function GetCurrentThread lib ”Carbon” (byref threadid as Integer) as short
declare function ThreadCurrentStackSpace lib ”Carbon” (threadid as Integer, byref size as Integer) as short
if GetCurrentThread(threadid)=0 then
if 0=ThreadCurrentStackSpace(threadid,size) then
MsgBox str(size)
end if
end if
End Sub
Notes: For Mac OS 9, use ”ThreadLib” instead of ”CarbonLib”. You can use # if if you like for that.
20.0.133
How to get the current timezone?
Plugin Version: all, Console & Web: No, Mac: Yes, Win: Yes, Linux: No. Answer:
You can use the TimeZoneMBS class or the CFTimeZoneMBS class.
Or code like below:
Example:
Function GMTOffsetInMinutes() as Integer
// Returns the offset of the current time to GMT in minutes.
// supports Mac OS and Windows, but not Linux yet (let me know if
// you have code for that, please)
//
// Note that the offset is not always an even multiple of 60, but
// there are also half hour offsets, even one 5:45h offset
// This version by Thomas Tempelmann ([email protected]) on 25 Nov 2005
// with a fix that should also make it work with future Intel Mac targets.
//
// Using code from various authors found on the RB NUG mailing list
dim result, bias, dayLightbias as Integer
dim info as memoryBlock
dim offset as Integer
# if targetMacOS then
Declare Sub ReadLocation lib ”Carbon” (location As ptr)
568
CHAPTER 20. THE FAQ
info = NewMemoryBlock(12)
ReadLocation info
if false then
// bad, because it does not work on Intel Macs:
’offset = info.short(9) * 256 + info.byte(11)
else
offset = BitwiseAnd (info.long(8), & hFFFFFF)
end
offset = info.short(9) * 256 + info.byte(11)
offset = offset \60
return offset
# endif
# if targetWin32 then
Declare Function GetTimeZoneInformation Lib ”Kernel32” ( tzInfoPointer as Ptr ) as Integer
// returns one of
// TIME ZONE ID UNKNOWN 0
// – Note: e.g. New Delhi (GMT+5:30) and Newfoundland (-3:30) return this value 0
// TIME ZONE ID STANDARD 1
// TIME ZONE ID DAYLIGHT 2
info = new MemoryBlock(172)
result = GetTimeZoneInformation(info)
bias = info.Long(0)
// note: the original code I found in the NUG archives used Long(84) and switched to Long(0)
// only for result=1 and result=2, but my tests found that Long(0) is also the right value for result=0
if result = 2 then
daylightBias = info.long(168)
end if
offset = - (bias + dayLightbias)
return offset
# endif
End Function
20.0.134
How to get the current window title?
Plugin Version: all, Console & Web: No, Mac: Yes, Win: No, Linux: No. Answer: The code below returns
the current window title for the frontmost window on Mac OS X if Accessibilty services are
569
Example:
Function CurrentWindowTitle() As string
dim SystemWideElement,FocusedApplicationElement,FocusedWindowElement as AXUIElementMBS
dim FocusedApplication,FocusedWindow,Title as AXValueMBS
dim s as String
dim cs as CFStringMBS
SystemWideElement=AccessibilityMBS.SystemWideAXUIElement
if SystemWideElement<>nil then
FocusedApplication=SystemWideElement.AttributeValue(AccessibilityMBS.kAXFocusedApplicationAttribute)
if FocusedApplication.Type=AccessibilityMBS.kAXUIElementMBSTypeID then
FocusedApplicationElement=new AXUIElementMBS
FocusedApplicationElement.Handle=FocusedApplication.Handle
FocusedApplicationElement.RetainObject
FocusedWindow=FocusedApplicationElement.AttributeValue(AccessibilityMBS.kAXFocusedWindowAttribute)
if FocusedWindow<>nil and AccessibilityMBS.kAXUIElementMBSTypeID=FocusedWindow.Type then
FocusedWindowElement=new AXUIElementMBS
FocusedWindowElement.Handle=FocusedWindow.Handle
FocusedWindowElement.RetainObject
Title=FocusedWindowElement.AttributeValue(AccessibilityMBS.kAXTitleAttribute)
if Title<>nil and Title.Type=kCFStringMBSTypeID then
cs=new CFStringMBS
cs.handle=Title.Handle
cs.RetainObject
Return cs.str
end if
end if
end if
end if
End Function
20.0.135
How to get the cursor blink interval time?
Plugin Version: all, Console & Web: No, Mac: Yes, Win: No, Linux: No. Answer: On Mac OS you can
use GetCaretTime from the toolbox.
Example:
declare function GetCaretTime lib ”Carbon” () as Integer
MsgBox str(GetCaretTime())+” ticks”
570
CHAPTER 20. THE FAQ
Notes: 60 ticks make one second.
20.0.136
How to get the list of the current selected files in the Finder?
Plugin Version: all, Console & Web: No, Mac: Yes, Win: No, Linux: No. Answer:
Use the AppleScript like this one:
tell application ”finder”
return selection
end tell
Which translates into this AppleEvent:
Process(”Finder”).SendAE ”core,getd,’—-’:obj { form:prop, want:type(prop), seld:type(sele), from:’null’() }
”
and as Realbasic code it looks like this:
Example:
dim
dim
dim
dim
dim
dim
ae as appleevent
o1 as appleeventObjectSpecifier
f as folderItem
aList as appleeventdescList
i as Integer
dateiname as string
// setup the AppleEvent
o1=getpropertyObjectDescriptor( nil, ”sele”)
ae= newappleEvent(”core”, ”getd”, ”MACS”)
ae.objectSpecifierParam(”—-”)=o1
// send it
if ae.send then
// got the list
alist=ae.replyDescList
// now show the list of filename into an editfield:
for i=1 to alist.count
f=alist.folderItemItem(i)
dateiname=f.name
571
// editfield1 with property ”mulitline=true”!
editfield1.text=editfield1.text + dateiname + chr(13)
next
end if
20.0.137
How to get the Mac OS system version?
Plugin Version: all, Console & Web: No, Mac: Yes, Win: No, Linux: No. Answer: The following code
queries the value and displays the version number:
Example:
dim
dim
dim
dim
first as Integer
second as Integer
third as Integer
l as Integer
if System.Gestalt(”sysv”,l) then
Third=Bitwiseand(l,15)
second=Bitwiseand(l\16,15)
first=Bitwiseand(l\256,15)+10*Bitwiseand(l\256\16,15)
end if
if First>=10 then
msgbox ”Mac OS X ”+str(First)+”.”+str(Second)+”.”+str(third)
else
msgbox ”Mac OS ”+str(First)+”.”+str(Second)+”.”+str(third)
end if
20.0.138
How to get the Mac OS Version using System.Gestalt?
Plugin Version: all, Console & Web: No, Mac: Yes, Win: No, Linux: No. Answer: Try this code:
Example:
Dim s As String
Dim b As Boolean
Dim i, resp as Integer
// Systemversion
b = System.Gestalt(”sysv”, resp)
If b then
s = Hex(resp)
572
CHAPTER 20. THE FAQ
For i =Len(s)-1 DownTo 1
s=Left(s,i)+”.”+Mid(s,i+1)
Next
MsgBox ”Systemversion: Mac OS ” + s
end if
Notes: The MBS Plugin has a SystemInformationMBS.OSVersionString function for this.
20.0.139
How to get the screensize excluding the task bar?
Plugin Version: all, Console & Web: No, Mac: No, Win: Yes, Linux: No. Answer: Try this code:
Notes: Use the Screen class with the available* properties.
20.0.140
How to get the size of the frontmost window on Windows?
Plugin Version: all, Console & Web: No, Mac: No, Win: Yes, Linux: No. Answer: Try this code:
Notes:
Make yourself a class for the WindowRect with four properties:
Bottom as Integer
Left as Integer
Right as Integer
Top as Integer
Add the following method to your class:
Sub GetWindowRect(windowhandle as Integer)
dim err as Integer
dim mem as memoryBlock
# if targetwin32 then
Declare Function GetWindowRect Lib ”user32.dll” (hwnd as Integer, ipRect As Ptr) as Integer
mem = newmemoryBlock(16)
err = GetWindowRect(windowhandle, mem)
Left = mem.long(0)
Top = mem.Long(4)
Right = mem.Long(8)
Bottom = mem.Long(12)
# endif
573
End Sub
Good to use for the MDI Master Window!
20.0.141
How to get the source code of a HTMLViewer?
Plugin Version: all, Console & Web: No, Mac: Yes, Win: No, Linux: No. Answer: Try this code:
Example:
// for Windows:
msgbox HTMLViewer1.IEHTMLTextMBS
// for Mac OS X:
msgbox HTMLViewer1.mainFrameMBS.dataSource.data
20.0.142
How to handle really huge images with GraphicsMagick or ImageMagick?
Plugin Version: all, Console & Web: No, Mac: Yes, Win: Yes, Linux: Yes. Answer: Sometimes it may be
better to use an extra application to process images.
Notes:
A typical 32 bit app made with Xojo (Real Studio) can use around 1.8 GB on Windows and 3 GB on Mac OS
X. Some images may be huge, so that processing them causes several copies of the image to be in memory.
With a 500 MB image in memory, doing a scale or rotation may require a temp image. So with source, temp
and dest images with each 500 MB plus your normal app memory usage, you may hit the limit of Windows
with 1.8 GB.
In that case it may be worth running a tool like gm in the shell class. gm is the command line version
of GraphicsMagick. There you can run the 64 bit version which is not limited in memory like your own
application. Also you can monitor progress and keep your app responsive.
20.0.143
How to handle tab key for editable cells in listbox?
Plugin Version: all, Console & Web: No, Mac: Yes, Win: Yes, Linux: Yes. Answer: Use code like this
function:
Example:
574
CHAPTER 20. THE FAQ
Function HandleTabInList(list as listbox, row as Integer, column as Integer, key as String) As Boolean
// Handle tab character in Listbox.CellKeyDown event
Select case asc(key)
case 9
if Keyboard.AsyncShiftKey then
// back
// look for column left
for i as Integer = column-1 downto 0
if list.ColumnType(i) >= list.TypeEditable then
list.EditCell(row, i)
Return true
end if
next
// not found, so look in row before
row = row - 1
if row >= 0 then
for i as Integer = list.ColumnCount-1 downto 0
if list.ColumnType(i) >= list.TypeEditable then
list.EditCell(row, i)
Return true
end if
next
end if
else
// forward
// look for column right
for i as Integer = column+1 to list.ColumnCount-1
if list.ColumnType(i) >= list.TypeEditable then
list.EditCell(row, i)
Return true
end if
next
// not found, so look in row below
row = row + 1
if row <list.ListCount then
for i as Integer = 0 to list.ColumnCount-1
if list.ColumnType(i) >= list.TypeEditable then
list.EditCell(row, i)
Return true
end if
next
end if
end if
575
end Select
End Function
Notes:
You call it from CellKeyDown event like this:
EventHandler Function CellKeyDown(row as Integer, column as Integer, key as String) As Boolean
if HandleTabInList(me, row, column, key) then Return true
End EventHandler
As you see in the code, we handle tab and shift + tab for moving back and forward. Also we wrap to previous/next row if needed. Feel free to extend this to wrap from last to first row or create a new row for editing.
20.0.144
How to hard link MapKit framework?
Plugin Version: all, Console & Web: No, Mac: Yes, Win: Yes, Linux: Yes. Answer: Our MapKit classes
weak link the framework. If you need hard linking it for the App Store, you can add this method to a class:
Example:
Sub ReferenceMapKit()
// just put this in window or app class
# if TargetMachO and Target64Bit then
Declare sub testing Lib ”MapKit” Selector ”test” (id as ptr)
testing(nil)
# endif
End Sub
Notes:
No need to call the method.
Just having it in a window or app, will cause the compiler to hard link the framework.
20.0.145
How to have a PDF downloaded to the user in a web application?
Plugin Version: all, Console & Web: No, Mac: Yes, Win: Yes, Linux: Yes. Answer: You can use a
WebHTMLViewer control and load the PDF file with the PDF plugin from the browser.
Example:
576
CHAPTER 20. THE FAQ
dim CurrentFile as WebFile // a property of the WebPage
// define the PDF file
CurrentFile = new WebFile
CurrentFile.Filename = ”test.pdf”
CurrentFile.MIMEType = ”application/pdf”
CurrentFile.Data = ”some pdf data” // MyDynaPDF.GetBuffer
CurrentFile.ForceDownload = true
// start the download
showurl(CurrentFile.url)
Notes: See our Create PDF example for the Real Studio Web Edition.
20.0.146
How to hide all applications except mine?
Console & Web: No, Mac: Yes, Win: No, Linux: No. Answer: The code below will on Mac OS hide all
applications except your one:
Example:
dim p as new ProcessMBS
p.GetFirstProcess
do
if not p.FrontProcess then
p.Visible=false
end if
loop until not p.GetNextProcess
20.0.147
How to hide script errors in HTMLViewer on Windows?
Plugin Version: all, Console & Web: No, Mac: No, Win: Yes, Linux: No. Answer: Set Internet Explorer
to silent mode with code like this:
Example:
htmlviewer1. ole.Content.value(”Silent”) = True
Notes: Simply put this code in the open event of your htmlviewer control (using me instead of htmlviewer1).
577
20.0.148
How to hide the grid/background/border in ChartDirector?
Plugin Version: all, Console & Web: No, Mac: Yes, Win: Yes, Linux: Yes. Answer: If you want to hide
something in a chart, simply assign the kTransparent constant as color.
20.0.149
How to hide the mouse cursor on Mac?
Plugin Version: all, Console & Web: No, Mac: Yes, Win: No, Linux: No. Answer: Try this declare:
Example:
Declare Sub HideCursor Lib ”Carbon” () Inline68K(”A852”)
HideCursor
Notes: The MBS Plugin has this function and supports it on Windows, too.
20.0.150
How to insert image to NSTextView or TextArea?
Plugin Version: all, Console & Web: No, Mac: Yes, Win: Yes, Linux: Yes. Answer: With NSTextViewMBS
you can use this code to insert file:
Example:
// insert a file to textview
Public Sub InsertFile(textview as NSTextViewMBS, f as FolderItem)
// read to file
dim b as BinaryStream = BinaryStream.Open(f)
dim s as string = b.Read(b.Length)
// build wrapper
dim fileWrapper as NSFileWrapperMBS = NSFileWrapperMBS.initRegularFileWithContents(s)
fileWrapper.preferredFilename = f.name
// make attachment
dim fileAttachment as new NSTextAttachmentMBS(fileWrapper)
dim attributedString as NSAttributedStringMBS = NSAttributedStringMBS.attributedStringWithAttachment(fileAttachment)
// add to a NSTextViewMBS
textview.insertText attributedString
End Sub
578
CHAPTER 20. THE FAQ
Notes: For TextArea you can query the underlaying NSTextViewMBS object via TextArea.NSTextViewMBS
method.
20.0.151
How to jump to an anchor in a htmlviewer?
Plugin Version: all, Console & Web: No, Mac: Yes, Win: Yes, Linux: No. Answer: You can use javascript
to change the current window’s location.
Example:
// load website
htmlviewer1.LoadURL ”http://www.monkeybreadsoftware.net/addressbook-abpersonmbs.shtml”
// later jump to anchor named ”16”:
if TargetWin32 then
call HTMLViewer1.IERunJavaScriptMBS ”window.location = ””# 16”””
elseif TargetMacOS then
call HTMLViewer1.EvaluateJavaScriptMBS ”window.location = ””# 16”””
else
// not supported
end if
20.0.152
How to keep a movieplayer unclickable?
Plugin Version: all, Console & Web: No, Mac: Yes, Win: Yes, Linux: Yes. Answer: To keep the user away
from clicking on a playing Movie you can just drop a Canvas in front of the Movieplayer and take the clicks
there.
Example:
Function Canvas1.MouseDown(X as Integer, Y as Integer) as boolean
return true // take it and do nothing
End Function
20.0.153
How to keep my web app from using 100% CPU time?
Plugin Version: all, Console & Web: No, Mac: Yes, Win: Yes, Linux: Yes. Answer: On Linux and Mac
OS X you can use renice command in the terminal. On Windows use the task manager to reduce priority.
Notes:
579
If you launch your app with nohup on Linux or Mac OS X like this from the terminal or a script:
nohup /webapps/MyApp/MyApp &
you can simply have a second line saying this:
renice 20 $ !
which tells the system to lower priority to lowest value for the latest background process.
20.0.154
How to kill a process by name?
Plugin Version: all, Console & Web: No, Mac: Yes, Win: Yes, Linux: Yes. Answer: You can kill a process
(or application) by name if you loop over all the processes and kill the one you need.
Example:
dim p as new ProcessMBS
p.GetfirstProcess ’ get first
do
if p.name = ”TextEdit” then
call p.KillProcess
Return
end if
loop until not p.GetNextProcess
Notes: You may want to check the result of killProcess function. Not every user is allowed to kill every
application.
20.0.155
How to know how many CPUs are present?
Plugin Version: all, Console & Web: No, Mac: Yes, Win: No, Linux: No. Answer: Try this function:
Example:
Function GetCPUCount() as Integer
Declare Function MPProcessors Lib ”Carbon” () as Integer
Return MPProcessors()
End Function
580
CHAPTER 20. THE FAQ
Notes: Your app will than need that library to launch on Classic. To avoid this the MBS plugin checks if
this library is available and return 1 if it’s not available.
20.0.156
How to know if a movie is finished?
Plugin Version: all, Console & Web: No, Mac: Yes, Win: Yes, Linux: No. Answer: This code can help you
althrough it’s not perfect:
Example:
Declare Function IsMovieDone Lib ”QuickTime” (theMovie as Integer) as Integer
if IsMovieDone(moviePlayer1.movie.handle) <>0 then
//movie is finished
end if
Notes: But be carefull! It crashes sometimes for an unknown reason!?
20.0.157
How to know if QuickTime is installed on any target and can play
MPEG 4 movies?
Plugin Version: all, Console & Web: No, Mac: Yes, Win: Yes, Linux: No. Answer: Try this code:
Example:
dim q as QTComponentInformationMBS
q=new QTComponentInformationMBS
// ”eat ” = Movie importers
while q.NextComponentOfType(”eat ”)
if q.SubType=”MP4 ” then
MsgBox ”found: ”+q.Name+ ” codec”
end if
wend
Notes: If you find a MP4 movie importing codec you can be sure that a MP4 movie can be opened.
581
20.0.158
How to know if QuickTime is installed on any target?
Plugin Version: all, Console & Web: No, Mac: Yes, Win: Yes, Linux: No. Answer: Try this function:
Example:
Dim theEffect as QTEffect
theEffect=GetQTCrossFadeEffect
if theEffect = nil then
msgBox ”QuickTime is not installed.”
else
msgBox ”Quicktime is installed.”
end if
Notes: The problem with this code is that it checks only if the QuickTime part of the cross fade effect is
available. Use the QTComponentInformationMBS to check for the features you really need.
20.0.159
How to know the calling function?
Plugin Version: all, Console & Web: No, Mac: Yes, Win: Yes, Linux: Yes. Answer: On Mac you can use
a helper function like this this code:
Example:
Public Function CallingFunction() as string
// Query name of calling function of a function
# Pragma BreakOnExceptions false
try
// raise a dummy exception
dim r as new NilObjectException
raise r
catch x as NilObjectException
// get stack
dim stack() as string = x.Stack
// pick function name and return
dim name as string = stack(2)
Return name
end try
582
CHAPTER 20. THE FAQ
End Function
Notes: You need to include function names in your application.
20.0.160
How to launch an app using it’s creator code?
Plugin Version: all, Console & Web: No, Mac: Yes, Win: No, Linux: No. Answer: Send an AppleEvent
”oapp” with the creator code to the Finder (”MACS”):
Example:
Dim a as AppleEvent
dim creator as string
creator = ”MSIE” ’ here the Internet Explorer
a = NewAppleEvent(”aevt”, ”odoc”, ”MACS”)
a.Timeout = -1
a.ObjectSpecifierParam(”—-”) = GetUniqueIDObjectDescriptor(”appf”, nil, creator)
if not a.send then
msgBox ”An error has occured”
else
end if
20.0.161
How to launch disc utility?
Plugin Version: all, Console & Web: No, Mac: Yes, Win: Yes, Linux: Yes. Answer: You can use this code:
Example:
dim f as FolderItem = LaunchServicesFindApplicationForInfoMBS(””,”com.apple.DiskUtility”,””)
if f<>Nil then
f.Launch
end if
Notes: This works even if people renamed the disc utility or moved it to another folder.
583
20.0.162
How to make a lot of changes to a REAL SQL Database faster?
Plugin Version: all, Console & Web: No, Mac: Yes, Win: Yes, Linux: Yes. Answer: You may try to embed
your changes to the database between two transaction calls.
Example:
dim db as Database // some database
db.SQLExecute ”BEGIN TRANSACTION”
// Do some Stuff
db.SQLExecute ”END TRANSACTION”
Notes: This can increase speed by some factors.
20.0.163
How to make a NSImage object for my retina enabled app?
Plugin Version: all, Console & Web: No, Mac: Yes, Win: No, Linux: No. Answer: You can use code like
this:
Example:
Function NewRetinaImage(pic as Picture, mask as Picture = nil) As NSImageMBS
// first make a NSImageMBS from it
dim n as new NSImageMBS(pic, mask)
// now set to half the size, so we have 2x pixels for the image
n.size = new NSSizeMBS(n.width/2, n.height/2)
// and return
Return n
End Function
Notes:
The thing to do is to have 2x the pixels, but assign a size to the image which gives it the right size in points.
You can pass the NSImageMBS from here to NSMenuItemMBS. For Retina displays, the full resolution is
used. For others it will be reduced.
20.0.164
How to make a window borderless on Windows?
Plugin Version: all, Console & Web: No, Mac: No, Win: Yes, Linux: No. Answer: Try this declares:
Example:
584
CHAPTER 20. THE FAQ
// Sets window to borderless popup type, and sets its initial dimensions.
// Call this method, then Win32SetBorderlessPos, and then RB’s Show
// method. Use RB Frame type 7 (Global Floating Window).
Const
Const
Const
Const
Const
SWP NOMOVE = & H2
SWP FRAMECHANGED = & H20
HWND TOPMOST = -1
GWL STYLE = -16
WS POPUPWINDOW = & H80880000
Dim styleFlags as Integer
# If TargetWin32 Then
Declare Function SetWindowLong Lib ”user32” Alias ”SetWindowLongA” (hwnd as Integer, nIndex as
Integer, dwNewLong as Integer) as Integer
Declare Function SetWindowPos Lib ”user32” (hwnd as Integer, hWndInstertAfter as Integer, x as Integer,
y as Integer, cx as Integer, cy as Integer, flags as Integer) as Integer
styleFlags = SetWindowLong( w.WinHWND, GWL STYLE, WS POPUPWINDOW )
styleFlags = BitwiseOr( SWP FRAMECHANGED, SWP NOMOVE )
styleFlags = SetWindowPos( w.WinHWND, HWND TOPMOST, 0, 0, wd, ht, styleFlags )
# EndIf
20.0.165
How to make an alias using AppleEvents?
Plugin Version: all, Console & Web: No, Mac: Yes, Win: No, Linux: No. Answer: Try this code:
Example:
Sub
dim
dim
dim
MakeAlias(folder as folderitem, target as folderitem, aliasname as string)
ev as AppleEvent
myResult as boolean
properties as AppleEventRecord
ev = NewAppleEvent(”core”,”crel”,”MACS”)
ev.MacTypeParam(”kocl”) = ”alis”
ev.FolderItemParam(”to ”) = target
ev.FolderItemParam(”insh”) = folder
properties=new AppleEventRecord
properties.StringParam(”pnam”)=aliasname
ev.RecordParam(”prdt”)=properties
585
myResult = ev.send
// true on success, false on error
End Sub
Notes:
Call it like this:
MakeAlias SpecialFolder.Desktop, SpecialFolder.Desktop.Child(”Gif Copy.rb”), ”test.rb alias”
Seems to not work on Mac OS X 10.6
20.0.166
How to make an application smaller?
Plugin Version: all, Console & Web: No, Mac: Yes, Win: Yes, Linux: Yes. Answer:
If you use an older copy of REALbasic, you should try to compile for 68k only instead of PPC. It’s a little
bit slower, but code is much smaller.
On any Mac OS target you can save your images as JPEG and drop the into your application. REALbasic
will include them as JPEGs into the Mac applications (convert to BMP for Windows). This will make the
resources of your application smaller, but requires that the user has QuickTime 2.5 or newer installed.
20.0.167
How to make AppleScripts much faster?
Plugin Version: all, Console & Web: No, Mac: Yes, Win: No, Linux: No. Answer: use ”ignoring application
responses” like in this example:
Notes:
on run { fn,fpx,fpy }
ignoring application responses
tell app ”Finder” to set the position of folder fn to fpx,fpy
end ignoring
end run
20.0.168
How to make double clicks on a canvas?
Plugin Version: all, Console & Web: No, Mac: Yes, Win: No, Linux: No. Answer:
Update: Newer Xojo versions support DoubleClick event, so you don’t need this code.
586
CHAPTER 20. THE FAQ
Here’s my tip from the tips list on how to add a double-click event to the Canvas control. The technique
could easily be used for a window or any Rectcontrol:
Because of its built-in drawing methods, the Canvas control is often used to create custom interface controls.
But while the Canvas control has event handlers for most mouse events, it doesn’t have an event handler
for DoubleClick events. Fortunately, you can add a double-click event handler to a Canvas control easily.
Basically, you’re going to create a new class based on Canvas and add a double-click event to that. You can
then use the new class anytime you need a Canvas with a double-click event.
To create a new Canvas class with a DoubleClick event handler, do this:
1. Add a new class to your project.
2. Set the Super property of the new class to ”Canvas”.
3. Change the name of this new class to ”DoubleClickCanvas”.
A double-click occurs when two clicks occur within the users double-click time (set in the Mouse control
panel on both Macintosh and Windows) and within five pixels of each other. So, you’ll need a few properties
to store when and where the last click occurred.
4. Add a new property with the following declaration and mark it as private: lastClickTicks as Integer
5. Add a new property with the following declaration and mark it as private: lastClickX as Integer
6. Add a new property with the following declaration and mark it as private: lastClickY as Integer
Since the Canvas control doesn’t have a DoubleClick event, you will need to add one.
7. Add a new event to your class by choosing New Event from the Edit menu and enter ”DoubleClick” as
the event name.
Double-clicks occur on MouseUp. In order for the mouseUp event to fire, you must return True in the
MouseDown event.
8. In the MouseDown event, add the following code:
Return True
In the MouseUp event, you will need to determine what the users double-click time is. This value is represented on both the Mac and Windows in ticks. A tick is 1/60th of a second. Since there isn’t a built-in
function for this, you’ll need to make a toolbox call. The mouseUp event code below makes the appropriate
toolbox call for both Macintosh and Windows. It then compares the time of the users last click to the time
of the current click and compares the location of the users last click to the location of the current click.
9. Add the following code to the MouseUp event:
587
dim doubleClickTime, currentClickTicks as Integer
# if targetMacOS then
Declare Function GetDblTime Lib ”Carbon” () as Integer
doubleClickTime = GetDblTime()
# endif
# if targetWin32 then
Declare Function GetDoubleClickTime Lib ”User32.DLL” () as Integer
doubleClickTime = GetDoubleClickTime()/60 // convert to ticks from milliseconds
# endif
currentClickTicks = ticks
//if the two clicks happened close enough together in time
if (currentClickTicks - lastClickTicks) <= doubleClickTime then
//if the two clicks occured close enough together in space
if abs(X - lastClickX) <= 5 and abs(Y - LastClickY) <= 5 then
DoubleClick //a double click has occured so call the event
end if
end if
lastClickTicks = currentClickTicks
lastClickX = X
lastClickY = Y
10. Now to test out your new DoubleClickCanvas, drag the class from the Project window to a window in
your project to create an instance of it.
11. Double-click on the canvas you just added to your window to open the Code Editor. Notice that the
canvas has a DoubleClick event handler. In this event handler, add the following code:
BEEP
20.0.169
How to make my Mac not sleeping?
Plugin Version: all, Console & Web: No, Mac: Yes, Win: No, Linux: No. Answer: Just inform the Mac
OS about some system activity with code like this:
Example:
Sub UpdateSystemActivity()
# if TargetCarbon
declare function myUpdateSystemActivity lib ”Carbon” alias ”UpdateSystemActivity” (activity as Integer)
as short
588
const
const
const
const
const
CHAPTER 20. THE FAQ
OverallAct = 0 // Delays idle sleep by small amount */
UsrActivity = 1 // Delays idle sleep and dimming by timeout time */
NetActivity = 2 // Delays idle sleep and power cycling by small amount */
HDActivity = 3 // Delays hard drive spindown and idle sleep by small amount */
IdleActivity = 4 // Delays idle sleep by timeout time */
dim e as Integer
e=myUpdateSystemActivity(UsrActivity)
// you may react on an error if e is not 0 after the call.
# endif
End Sub
Notes:
You may use another constant if you prefer some different behavior.
Call it maybe every second.
20.0.170
How to make my own registration code scheme?
Plugin Version: all, Console & Web: No, Mac: No, Win: Yes, Linux: No. Answer: There are excellent articles about how to make a registratin code scheme, but you can also simply use our RegistrationEngineMBS
class.
Notes: If you need a license text, why not use the one from Real Studio as a starting point?
20.0.171
How to make small controls on Mac OS X?
Plugin Version: all, Console & Web: No, Mac: Yes, Win: No, Linux: No. Answer: You can try this code
on Mac OS X:
Example:
’/*
’* Use the control’s default drawing variant. This does not apply to
’* Scroll Bars, for which Normal is Large.
’*/
const kControlSizeNormal = 0
’/*
’* Use the control’s small drawing variant. Currently supported by
’* the Check Box, Combo Box, Radio Button, Scroll Bar, Slider and Tab
’* controls.
589
’*/
const kControlSizeSmall = 1
’/*
’* Use the control’s small drawing variant. Currently supported by
’* the Indeterminate Progress Bar, Progress Bar and Round Button
’* controls.
’*/
const kControlSizeLarge = 2
’/*
’* Control drawing variant determined by the control’s bounds. This
’* ControlSize is only available with Scroll Bars to support their
’* legacy behavior of drawing differently within different bounds.
’*/
const kControlSizeAuto = & hFFFF
const kControlSizeTag = ”size”
declare function SetControlData lib ”Carbon” (controlhandle as Integer, part as short, tagname as OSType, size as Integer, data as ptr) as short
dim m as MemoryBlock
m=NewMemoryBlock(2)
m.UShort(0)=kControlSizeSmall
Title=str(SetControlData(CheckBox1.Handle, 0, kControlSizeTag, 2, m))
20.0.172
How to mark my Mac app as background only?
Plugin Version: all, Console & Web: No, Mac: Yes, Win: No, Linux: No. Answer: You can run a build
script on each build with this code:
Example:
Dim App As String = CurrentBuildLocation + ”/” + CurrentBuildAppName + ”.app”
Call DoShellCommand(”/usr/bin/defaults write ” + App + ”/Contents/Info ””NSUIElement”” YES”)
Notes: This will set the NSUIElement flag to YES.
590
20.0.173
CHAPTER 20. THE FAQ
How to move a file or folder to trash?
Plugin Version: all, Console & Web: No, Mac: Yes, Win: Yes, Linux: Yes. Answer: Use code like below:
Example:
Function MoveToTrash(f as FolderItem) As Boolean
# if TargetMacOS then
dim r as FolderItem
dim e as Integer = MacFileOperationMBS.MoveObjectToTrashSync(f, r, MacFileOperationMBS.kFSFileOperationDefaultOptions)
if e = 0 then
Return true // Ok
end if
# elseif TargetWin32 then
dim w as new WindowsFileCopyMBS
dim flags as Integer = w.FileOperationAllowUndo + w.FileOperationNoErrorUI + w.FileOperationSilent
+ w.FileOperationNoConfirmation
if w.FileOperationDelete(f, flags) then
Return true // OK
end if
flags = w.FileOperationNoErrorUI + w.FileOperationSilent + w.FileOperationNoConfirmation
if w.FileOperationDelete(f, flags) then
Return true // OK
end if
# else
// Target not supported
break
Return false
# endif
End Function
Notes:
If you want to move a file to trash, you could use f.movefileto f.trashfolder, but that will overwrite existing
files in the trash. You can use our MacFileOperationMBS class to move a file on Mac to the trash. And it
uses the same code as the Finder, so files are renamed when the same name is already in use in the trash:
On Windows we use WindowsFileCopyMBS class.
Requires Mac OS X 10.5.
591
20.0.174
How to move an application to the front using the creator code?
Plugin Version: all, Console & Web: No, Mac: Yes, Win: No, Linux: No. Answer: This makes SimpleText
(Code ttxt) to the frontmost application:
Example:
dim a as appleevent
a=newappleEvent(”misc”,”actv”,”ttxt”)
if a.send then
end if
Notes: (Code is Mac only)
20.0.175
How to move file with ftp and curl plugin?
Plugin Version: all, Console & Web: No, Mac: Yes, Win: Yes, Linux: Yes. Answer: You can set post/pre
quotes to have ftp commands executed before or after the download/upload.
Example:
dim d as CURLMBS // your curl object
// rename/move file
dim ws() As String
ws.Append ”RNFR Temp.txt”
ws.append ”RNTO MyFile.txt”
d.SetOptionPostQuote(ws)
Notes:
Use SetOptionPostQuote, SetOptionPreQuote or SetOptionQuote.
The ftp commands you pass here are native ftp commands and not the commands you use with ftp applications. So rename is two commands. First RNFR to tell where to rename from and second RNTO with the
new file name. To delete use DELE and the file path.
20.0.176
How to normalize string on Mac?
Plugin Version: all, Console & Web: No, Mac: Yes, Win: Yes, Linux: Yes. Answer: Use code like below:
Example:
592
CHAPTER 20. THE FAQ
Function Normalize(t as string) As string
const kCFStringNormalizationFormD = 0 // Canonical Decomposition
const kCFStringNormalizationFormKD = 1 // Compatibility Decomposition
const kCFStringNormalizationFormC = 2 // Canonical Decomposition followed by Canonical Composition
const kCFStringNormalizationFormKC = 3 // Compatibility Decomposition followed by Canonical Composition
dim s as CFStringMBS = NewCFStringMBS(t)
dim m as CFMutableStringMBS = s.Normalize(kCFStringNormalizationFormD)
Return m.str
End Function
Notes: This uses Apple’s CFString functions to normalize unicode variants.
20.0.177
How to obscure the mouse cursor on Mac?
Plugin Version: all, Console & Web: No, Mac: Yes, Win: No, Linux: No. Answer: Try this declare:
Example:
Declare Sub ObscureCursor Lib ”Carbon” ()
ObscureCursor
Notes: The MBS Plugin has this function, but it’s not supported for Windows.
20.0.178
How to open icon file on Mac?
Plugin Version: all, Console & Web: No, Mac: Yes, Win: No, Linux: No. Answer: Use the NSImageMBS
class like this:
Example:
dim f as FolderItem = SpecialFolder.Desktop.Child(”test.ico”)
dim n as new NSImageMBS(f)
window1.Backdrop = n.CopyPictureWithMask
593
20.0.179
How to open PDF in acrobat reader?
Plugin Version: all, Console & Web: No, Mac: Yes, Win: No, Linux: No. Answer: Try this code:
Example:
dim pdf as FolderItem = SpecialFolder.Desktop.Child(”test.pdf”)
// open PDF in Acrobat Reader on Mac:
// find app
dim bundleID as string = ”com.adobe.Reader”
dim app as FolderItem = LaunchServicesFindApplicationForInfoMBS(””, bundleID, ””)
if app<>nil then
// launch app with parameters
dim docs() as FolderItem
docs.Append pdf
dim param as new LaunchServicesLaunchParameterMBS
param.Defaults = true
param.Application = app
dim x as FolderItem = LaunchServicesOpenXMBS(docs, param)
// on failure, simply launch it
if x = nil then
pdf.Launch(true)
end if
else
pdf.Launch(true)
end if
Notes: On Windows, simply use pdf.launch or WindowsShellExecuteMBS.
20.0.180
How to open printer preferences on Mac?
Plugin Version: all, Console & Web: No, Mac: Yes, Win: No, Linux: No. Answer: You can use our
OpenMacOSXPreferencesPaneMBS function like this:
Example:
dim e as Integer = OpenMacOSXPreferencesPaneMBS(”PrintAndFax”)
if 0 = e then
594
CHAPTER 20. THE FAQ
MsgBox ”OK”
elseif e = -43 then
MsgBox ”File not found.”
else
MsgBox ”Error: ”+str(e)
end if
20.0.181
How to open special characters panel on Mac?
Plugin Version: all, Console & Web: No, Mac: Yes, Win: Yes, Linux: Yes. Answer: We have functions for
that in Cocoa and Carbon.
Example:
dim a as new NSApplicationMBS
a.orderFrontCharacterPalette
Notes:
For Cocoa, you can use orderFrontCharacterPalette method in NSApplicationMBS class.
Or simply for Carbon and Cocoa the ShowCharacterPaletteMBS method.
20.0.182
How to optimize picture loading in Web Edition?
Plugin Version: all, Console & Web: No, Mac: Yes, Win: Yes, Linux: Yes. Answer: Use the WebPicture
class.
Notes:
Take your picture and create a WebPicture object. Store this WebPicture in a property of the WebPage,
Session or app (as global as possible). On the first time you use this picture on an user session, the browser
will load it. Second time you use it, the browser will most likely pick it from the cache.
Having pictures in App or some module reuses the same picture for all sessions which reduces memory footprint.
This does not work well with pictures you change very often or use only for one webpage on one user.
If you like to see an example, check our Map example:
http://www.monkeybreadsoftware.de/realbasic/webapps.shtml
595
20.0.183
How to parse XML?
Plugin Version: all, Console & Web: No, Mac: Yes, Win: Yes, Linux: Yes. Answer: You can use code like
this:
Example:
dim s as string = ”<test><test /></test>”
try
dim x as new XmlDocument(s)
MsgBox ”OK”
catch xe as XmlException
MsgBox ”invalid XML”
end try
Notes: If you got an exception, you have a parse error.
20.0.184
How to play audio in a web app?
Plugin Version: all, Console & Web: No, Mac: Yes, Win: Yes, Linux: Yes. Answer: You can use the
HTML5 audio tag and control it with javscript.
Notes:
See our web apps here:
http://www.monkeybreadsoftware.de/realbasic/webapps.shtml
This is just another example app I made today. It plays a christmas song. The audio file is provided by the
application to the server, so no external web server is needed and this application can run stand alone. To
compile and run you need Real Studio 2010r5.
In the open event we search the audio files and open them as binarystreams. We create the two webfile
objects. Those webfiles are part of the app class, so we have them globally. There we set the data with the
content of our streams. We also define file names and mime types. They are needed so browser know what
we have here:
audioFileM4V = new WebFile
audioFileM4V.Data = bM.Read(BM.Length)
audioFileM4V.Filename = ”music.m4a”
audioFileM4V.MIMEType = ”audio/m4a”
audioFileOGG = new WebFile
audioFileOGG.Data = bO.Read(BO.Length)
596
CHAPTER 20. THE FAQ
audioFileOGG.Filename = ”music.ogg”
audioFileOGG.MIMEType = ”audio/ogg”
Next in the open event of the webpage we have a PageSource control. The location is set to be before
content. In the open event we define the html code for this. First we pick the URLs for the audio files.
Than we build the html to use the audio tag. As you see, we give it an ID for later use and have it preload
automatically. If you add an autoplay tag, you can have the audio play right away. Inside the audio tag we
have two sources so we provide audio for both Firefox (OGG) and Safari (MPEG4). Finally we have a text
to display if HTML5 audio tag is not supported.
You can set the source in the EditSource event:
dim urlo as string = app.audioFileOGG.URL
dim urlm as string = app.audioFileM4V.URL
me.Source = ”<audio id=””mymusic”” preload=””auto””><source src=”””+urlo+””” type=””audio/ogg””
/><source src=”””+urlm+””” type=””audio/mpeg”” />Your browser does not support the audio element.</audio>”
Next in the Play button we execute code to play the audio. This is a short javascript code which searches
in the html document for the element with the ID ”mymusic” which is the ID of our audio tag above. Once
we got the object, we call it’s play method to start playback.
me.ExecuteJavaScript(”document.getElementById(’mymusic’).play();”)
same for pause:
me.ExecuteJavaScript(”document.getElementById(’mymusic’).pause();”)
and finally for changing volume:
me.ExecuteJavaScript(”document.getElementById(’mymusic’).volume=”+str(me.Value/100.0)+”;”)
20.0.185
How to pretty print xml?
Plugin Version: all, Console & Web: No, Mac: Yes, Win: Yes, Linux: Yes. Answer: Use the XML
Transform method with the right XLS.
Notes:
Learn more here:
http://docs.xojo.com/index.php/XMLDocument.Transform
597
20.0.186
How to print to PDF?
Plugin Version: all, Console & Web: No, Mac: Yes, Win: Yes, Linux: Yes. Answer: This code below shows
how to redirect printing to a PDF file on Mac OS X.
Example:
// get Xojo printer setup
dim p as new PrinterSetup
// now put it into NSPrintInfo to manipulate
dim n as new NSPrintInfoMBS
n.SetupString = p.SetupString
// change destination to file
dim f as FolderItem = SpecialFolder.Desktop.Child(”test.pdf”)
n.SetSaveDestination(f)
// move back
p.SetupString = n.SetupString
// and print as usual
dim g as Graphics = OpenPrinter(p)
g.DrawString ”Hello World”, 20, 20
Notes: And you can use normal graphics class for that.
20.0.187
How to query Spotlight’s Last Open Date for a file?
Plugin Version: all, Console & Web: No, Mac: Yes, Win: No, Linux: No. Answer: You can use a
MDItemMBS objec to query this value:
Example:
Function LastOpenedDate(Extends F As FolderItem, DefaultOtherDates As Boolean = True) As Date
# If TargetMacOS Then
Dim xMDItem as New MDItemMBS(F)
Dim xDate as Variant
If xMDItem <>Nil Then
xDate = xMDItem.GetAttribute(xMDItem.kMDItemLastUsedDate).DateValue
If xDate IsA Date Then Return xDate
Else
If xDate <>Nil Then Break
End If
# EndIf
598
CHAPTER 20. THE FAQ
If DefaultOtherDates Then
If F.ModificationDate <>Nil Then Return F.ModificationDate
If F.CreationDate <>Nil Then Return F.CreationDate
End If
End Function
Notes: Thanks for Josh Hoggan for this example code.
20.0.188
How to quit windows?
Plugin Version: all, Console & Web: No, Mac: No, Win: Yes, Linux: No. Answer: Try this code:
Example:
# if targetwin32 then
dim i1,i2,r as Integer
declare function ExitWindowsEx lib ”user32” (uFlags as Integer, dwReserved as Integer) as Integer
i1 = 2
i2 = 0
r = ExitWindowsEx(i1,i2)
if r<>0 then
’ Error()
end if
# endif
Notes:
uFlags parameters:
’4
’0
’2
’1
=
=
=
=
EWX
EWX
EWX
EWX
Force
Logoff
Reboot
shutdown, should shut down computer
Also check the ExitWindowsMBS method.
20.0.189
How to read a CSV file correctly?
Plugin Version: all, Console & Web: No, Mac: Yes, Win: Yes, Linux: Yes. Answer: With all the rules for
quotes and delimiters, you can simply use the SplitCommaSeparatedValuesMBS method in our plugins like
599
this:
Example:
dim f as FolderItem = SpecialFolder.Desktop.Child(”test.csv”)
dim t as TextInputStream = f.OpenAsTextFile
while not t.EOF
dim s as string = t.ReadLine(encodings.ASCII)
dim items() as string = SplitCommaSeparatedValuesMBS(s, ”;”, ””””)
List.AddRow ””
dim u as Integer = UBound(items)
for i as Integer = 0 to u
List.Cell(List.LastIndex,i) = items(i)
next
wend
Notes: Please make sure you choose the right text encoding.
20.0.190
How to read the command line on windows?
Plugin Version: all, Console & Web: No, Mac: No, Win: Yes, Linux: No. Answer: Try this code:
Example:
# if targetwin32 then
dim line as string
Dim mem as MemoryBlock
Declare Function GetCommandLineA Lib ”kernel32” () As Ptr
mem=GetCommandLineA()
s=mem.cstring(0)
# endif
Notes: Newer Realbasic versions have a system.commandline property.
600
20.0.191
CHAPTER 20. THE FAQ
How to render PDF pages with PDF Kit?
Plugin Version: all, Console & Web: No, Mac: No, Win: Yes, Linux: No. Answer: Try this code:
Example:
// choose a file
dim f as FolderItem = SpecialFolder.Desktop.Child(”test.pdf”)
// open it as PDF Document
dim sourceFile as New PDFDocumentMBS(f)
if sourceFile.handle <>0 then // it is a PDF file
// get upper bound of pages
dim c as Integer = sourceFile.pageCount-1
// from first to last page
for n as Integer = 0 to c
// pick that page
dim page as PDFPageMBS = sourceFile.pageAtIndex(n)
// render to image
dim p as NSImageMBS = page.Render
// and convert to RB picture and display
Backdrop = p.CopyPictureWithMask
next
end if
Notes: PDFKit works only on Mac OS X.
20.0.192
How to restart a Mac?
Plugin Version: all, Console & Web: No, Mac: Yes, Win: No, Linux: No. Answer: Ask the Finder via
Apple Events:
Example:
dim ae as appleevent
ae=newappleEvent(”FNDR”,”rest”,”MACS”)
if not ae.send then
msgBox ”The computer couldn’t be restarted.”
end if
601
20.0.193
How to resume ftp upload with curl plugin?
Plugin Version: all, Console & Web: No, Mac: Yes, Win: Yes, Linux: Yes. Answer: CURL supports that
and you simply need to set the right options.
Notes:
First of course OptionUpload must be true. Second OptionFTPAppend must be true so the OptionResumeFrom is used. Store there (or in OptionResumeFromLarge) your start value.
Don’t forget to implement the read event and return data there as requested.
20.0.194
How to rotate a PDF page with CoreGraphics?
Plugin Version: all, Console & Web: No, Mac: Yes, Win: Yes, Linux: Yes. Answer: This code opens a
PDF and draws the first page into a new PDF with 90 rotation.
Example:
// Rotate a PDF page
// our files
dim sourcefile as FolderItem = SpecialFolder.Desktop.Child(”test.pdf”)
dim destfile as FolderItem = SpecialFolder.Desktop.Child(”rotated.pdf”)
// open PDF
dim pdf as CGPDFDocumentMBS = sourcefile.OpenAsCGPDFDocumentMBS
// query media size of first page
dim r as CGRectMBS = pdf.MediaBox(1)
// create new PDF
dim c as CGContextMBS = destfile.NewCGPDFDocumentMBS(r,”title”,”Author”,”Creator”)
// create rotated rectangle
dim nr as new CGRectMBS(0,0,r.Height,r.Width)
// create new page
c.BeginPage nr
c.SaveGState
const pi = 3.14159265
// rotate by 90
c.RotateCTM pi*1.5
602
CHAPTER 20. THE FAQ
// fix origin
c.TranslateCTM -r.width,0
// draw PDF
c.DrawCGPDFDocument pdf,r,1
// cleanup
c.RestoreGState
c.EndPage
c = nil
// show in PDF viewer
destfile.Launch
Notes: This code is Mac only as it needs CoreGraphics.
20.0.195
How to rotate image with CoreImage?
Plugin Version: all, Console & Web: No, Mac: Yes, Win: No, Linux: No. Answer: Use the code like the
one below:
Example:
// Rotate image with CoreImage
// load image
dim f as FolderItem = SpecialFolder.Desktop.Child(”test.png”)
dim image as new CIImageMBS(f)
// rotate 45 degree
dim n as new NSAffineTransformMBS
n.rotateByDegrees(45)
dim TransformFilter as new CIFilterAffineTransformMBS
TransformFilter.inputImage = image
TransformFilter.inputTransform = n
// get result
dim resultImage as CIImageMBS = TransformFilter.outputImage
// for saving to file
dim outputImage as NSImageMBS = resultImage.RenderNSImage(false)
f = SpecialFolder.Desktop.Child(”output.png”)
dim b as BinaryStream = BinaryStream.Create(f, true)
603
b.Write outputImage.PNGRepresentation
// as Real Studio picture object for display
dim pic as Picture = outputImage.CopyPictureWithMask
Backdrop = pic
20.0.196
How to run a 32 bit application on a 64 bit Linux?
Plugin Version: all, Console & Web: No, Mac: Yes, Win: Yes, Linux: Yes. Answer: Install 32 bit
compatibility libraries.
Notes:
The package is called ia32-libs for ubuntu (and others).
Some applications need to be run on a 32 bit system as they need some hardware related libraries. Like
libUSB or libHID for USB devices.
20.0.197
How to save a quicktime movie as a reference movie?
Plugin Version: all, Console & Web: No, Mac: Yes, Win: Yes, Linux: No. Answer: Example code is below:
Example:
// save as reference movie
dim f as FolderItem
dim m as movie
f=SpecialFolder.Desktop.Child(”test.mov”)
m=f.OpenAsMovie
f=SpecialFolder.Desktop.Child(”new movie.mov”)
msgbox str(m.SaveMBS(f,false,false))
20.0.198
How to save HTMLViewer to PDF with landscape orientation?
Plugin Version: all, Console & Web: No, Mac: Yes, Win: No, Linux: No. Answer: You can use NSPrintInfoMBS to change the options for PrintToPDFFile function.
Example:
// make it landscape
dim n as NSPrintInfoMBS = NSPrintInfoMBS.sharedPrintInfo
604
CHAPTER 20. THE FAQ
n.orientation = n.NSLandscapeOrientation
// save html to file
dim f as FolderItem = SpecialFolder.Desktop.Child(”test.pdf”)
call HTMLViewer1.PrintToPDFFileMBS(f,10,30,10,30)
Notes:
You may want to reset options later.
This code is only for Mac OS X.
20.0.199
How to save RTFD?
Plugin Version: all, Console & Web: No, Mac: Yes, Win: Yes, Linux: Yes. Answer: With NSTextViewMBS
you can use this code to save to RTFD:
Example:
// save text as RTFD including image attachments
dim f as FolderItem = GetSaveFolderItem(FileTypes1.ApplicationRtfd, ”test.rtfd”)
if f = nil then Return
dim a as NSAttributedStringMBS = textView.textStorage
dim w as NSFileWrapperMBS = a.RTFDFileWrapperFromRange(0, a.length, DocumentAttributes)
dim e as NSErrorMBS
if w.writeToFile(f, e) then
else
MsgBox e.LocalizedDescription
end if
Notes: For TextArea you can query the underlaying NSTextViewMBS object via TextArea.NSTextViewMBS
method.
20.0.200
How to scale a picture proportionally with mask?
Plugin Version: all, Console & Web: No, Mac: Yes, Win: Yes, Linux: Yes. Answer: For a proportional
scaling, we calculate the new picture size relative to the target maximum size.
Example:
605
Function ProportinalScaledWithMask(extends pic as Picture, Width as Integer, Height as Integer) As Picture
// Calculate scale factor
dim faktor as Double = min( Height / Pic.Height, Width / Pic.Width)
// Calculate new size
dim w as Integer = Pic.Width * faktor
dim h as Integer = Pic.Height * faktor
// create new picture
dim NewPic as new Picture(w,h,32)
// check if we have a mask and clear it
dim m as picture = pic.mask(False)
pic.mask = nil
// draw picture in the new size
NewPic.Graphics.DrawPicture Pic, 0, 0, w, h, 0, 0, Pic.Width, Pic.Height
if m <>nil then
// restore mask and scale it
pic.mask = m
NewPic.mask.Graphics.DrawPicture m, 0, 0, w, h, 0, 0, Pic.Width, Pic.Height
end if
// return result
Return NewPic
End Function
Notes: This version handles mask. As you see we actually have to remove mask in order to copy the picture
part correctly.
20.0.201
How to scale a picture proportionally?
Plugin Version: all, Console & Web: No, Mac: Yes, Win: Yes, Linux: Yes. Answer: For a proportional
scaling, we calculate the new picture size relative to the target maximum size.
Example:
Function ProportionalScaled(extends pic as Picture, Width as Integer, Height as Integer) As Picture
// Calculate scale factor
dim faktor as Double = min( Height / Pic.Height, Width / Pic.Width)
606
CHAPTER 20. THE FAQ
// Calculate new size
dim w as Integer = Pic.Width * faktor
dim h as Integer = Pic.Height * faktor
// create new picture
dim NewPic as new Picture(w,h,32)
// draw picture in the new size
NewPic.Graphics.DrawPicture Pic, 0, 0, w, h, 0, 0, Pic.Width, Pic.Height
// return result
Return NewPic
End Function
Notes:
This does not handle mask, but you can scale the mask the same way and assign it to the new picture.
(see other FAQ entry with mask)
20.0.202
How to scale/resize a picture?
Plugin Version: all, Console & Web: No, Mac: No, Win: Yes, Linux: No. Answer: There are several ways
to scale or resize a picture. The easiest way may be the ScaleMBS function in the Picture class.
Example:
dim Original,Scaled as Picture
Original=LogoMBS(500)
Scaled=Original.ScaleMBS(100,100,true)
Notes:
The plugin ways:
- The GWorld class which uses QuickTime. Includes nice Bicubic scaling with QuickTime 6.
- QTGraphicsImporterMBS and QTGraphicsExporterMBS can scale/resize.
- CoreImage scale filter may result in the fastest and best images on Mac OS X 10.4.
- NSImageMBS can scale, but is Mac OS X only.
- CGImageMBS can scale, but is Mac OS X only.
- CIImageMBS can scale, but is Mac OS X only.
- QuickTime Graphics exporter and importer can be connected to scale. (this was used more often a few
years ago)
- ImageMagick can scale very nice and crossplatform. But the ImageMagick libraries are big.
- The picture.ScaleMBS function is self written and results in equal output on Mac, Windows and Linux
without any additional libraries installed.
607
- Picture.ScalingMBS does crossplatform scaling with several modes.
with pure REALbasic:
- make a new picture and draw the old one with new size inside.
20.0.203
How to search with regex and use unicode codepoints?
Plugin Version: all, Console & Web: No, Mac: Yes, Win: Yes, Linux: Yes. Answer: You can specify
unicode characters in search string with backslash x and digits.
Example:
dim r as RegExMbs
dim s as string
dim c as Integer
s=”123 ABC 456”
r=new RegExMBS
if r.Compile(”..”) then
c=r.Execute(s,0)
MsgBox str(c)+” ”+str(r.Offset(0))+” ”+str(r.Offset(1))
// shows: 1 4 10
// 1 for ubound of the offset array
// 4 for 4 bytes before the matched pattern
// 10 for the 10 bytes before the end of the matched pattern
end if
r=new RegExMBS
if r.Compile(”.\xF6.”) then // finds using Unicode codepoint
c=r.Execute(s,0)
MsgBox str(c)+” ”+str(r.Offset(0))+” ”+str(r.Offset(1))
// shows: 1 4 10
// 1 for ubound of the offset array
// 4 for 4 bytes before the matched pattern
// 10 for the 10 bytes before the end of the matched pattern
end if
20.0.204
How to see if a file is invisible for Mac OS X?
Plugin Version: all, Console & Web: No, Mac: Yes, Win: No, Linux: No. Answer: Try this function:
Example:
608
CHAPTER 20. THE FAQ
Function Invisible(F As FolderItem) As Boolean
Dim TIS As TextInputStream
Dim S,All As String
Dim I as Integer
dim g as folderitem
If Left(F.Name,1)=”.” or not f.visible Then
Return True
End If
g=F.Parent.Child(”.hidden”)
If g.Exists Then
TIS=g.OpenAsTextFile
if tis<>Nil then
All=TIS.ReadAll
For I=1 to CountFields(All,Chr(11))
S=NthField(All, Chr(11), I)
If S=F.name Then
Return True
End If
Next
end if
End if
End Function
20.0.205
How to set cache size for SQLite or REALSQLDatabase?
Plugin Version: all, Console & Web: No, Mac: Yes, Win: Yes, Linux: Yes. Answer: You use the pragma
cache size command on the database.
Example:
// set cache size to 20000 pages which is about 20 MB for default page size
dim db as REALSQLDatabase
db.SQLExecute ”PRAGMA cache size = 20000”
Notes:
Default cache size is 2000 pages which is not much.
You get best performance if whole database fits in memory.
At least you should try to have a cache big enough so you can do queries in memory.
You only need to call this pragma command once after you opened the database.
609
20.0.206
How to set the modified dot in the window?
Plugin Version: all, Console & Web: No, Mac: Yes, Win: No, Linux: No. Answer: Try this declares:
Example:
window1.ModifiedMBS=true
20.0.207
How to show a PDF file to the user in a Web Application?
Plugin Version: all, Console & Web: No, Mac: Yes, Win: Yes, Linux: Yes. Answer: You can use a
WebHTMLViewer control and load the
Example:
dim CurrentFile as WebFile // a property of the WebPage
// define the PDF file
CurrentFile = new WebFile
CurrentFile.Filename = ”test.pdf”
CurrentFile.MIMEType = ”application/pdf”
CurrentFile.Data = ”some pdf data” // MyDynaPDF.GetBuffer
// load into html viewer
HTMLViewer1.URL = CurrentFile.URL
Notes:
See our Create PDF example for the Real Studio Web Edition.
http://www.monkeybreadsoftware.de/realbasic/webapps.shtml
20.0.208
How to show Keyboard Viewer programmatically?
Console & Web: No, Mac: Yes, Win: No, Linux: No. Answer: Use Realbasic or AppleScript to launch the
KeyboardViewerServer.app.
Example:
dim a as new AppleScriptMBS
dim text as string
dim lines(-1) as string
lines.append ”set theApplication to ””KeyboardViewerServer”””
lines.append ”set thePath to ””/System/Library/Components/KeyboardViewer.component/Contents/SharedSupport/KeyboardViewerServer.app”””
lines.append ””
610
CHAPTER 20. THE FAQ
lines.append ”set POSIXPath to ((POSIX file thePath) as string)”
lines.append ”tell application ””System Events”” to set isRunning to 0 <(count (application processes whose
name is theApplication))”
lines.append ”if isRunning then tell application POSIXPath to quit”
lines.append ”delay 0.15”
lines.append ””
lines.append ”ignoring application responses”
lines.append ” tell application POSIXPath to run”
lines.append ”end ignoring”
text=join(lines,EndOfLine.macintosh)
a.Compile text
a.Execute
Notes:
AppleScript code:
set theApplication to ”KeyboardViewerServer”
set thePath to ”/System/Library/Components/KeyboardViewer.component/Contents/SharedSupport/KeyboardViewerServer.app”
set POSIXPath to ((POSIX file thePath) as string)
tell application ”System Events” to set isRunning to 0 <(count (application processes whose name is theApplication))
if isRunning then tell application POSIXPath to quit
delay 0.15
ignoring application responses
tell application POSIXPath to run
end ignoring
20.0.209
How to show the mouse cursor on Mac?
Plugin Version: all, Console & Web: No, Mac: Yes, Win: No, Linux: No. Answer: Try this declare:
Example:
Declare Sub ShowCursor Lib ”Carbon” ()
ShowCursor
611
Notes: The MBS Plugin has this function and supports it on Windows, too.
20.0.210
How to shutdown a Mac?
Plugin Version: all, Console & Web: No, Mac: Yes, Win: No, Linux: No. Answer: Ask the Finder via
Apple Events:
Example:
dim ae as appleevent
ae=newappleEvent(”FNDR”,”shut”,”MACS”)
if not ae.send then
msgBox ”The computer couldn’t be shutdown.”
end if
Notes:
Or toolbox call (Attention: This method will stop the computer
immediataly: No document asked to be saved, all applications quitting
without knowing).
Declare Sub ShutDwnPower Lib ”Carbon” ()
ShutDwnPower
20.0.211
How to sleep a Mac?
Plugin Version: all, Console & Web: No, Mac: Yes, Win: No, Linux: No. Answer: Ask the Finder via
Apple Events:
Example:
dim ae as appleevent
ae=newappleEvent(”FNDR”,”slep”,”MACS”)
if not ae.send then
msgBox ”The computer doesn’t want to sleep.”
end if
612
20.0.212
CHAPTER 20. THE FAQ
How to speed up rasterizer for displaying PDFs with DynaPDF?
Plugin Version: all, Console & Web: No, Mac: Yes, Win: Yes, Linux: Yes. Answer: Here a few speed tips:
Notes:
• Use the DynaPDFRasterizerMBS function instead of our render functions.
• Reuse DynaPDFRasterizerMBS as long as the target picture size doesn’t change.
• Import only the PDF pages you want to display.
• Let DynaPDF do zooming, rotating or other effects instead of you change it.
20.0.213
How to use PDFLib in my RB application?
Plugin Version: all, Console & Web: No, Mac: Yes, Win: Yes, Linux: Yes. Answer: The PDFlib plugin
was discontinued in favor of our DynaPDF plugin.
Notes: If you need help to move, please contact us.
20.0.214
How to use quotes in a string?
Plugin Version: all, Console & Web: No, Mac: Yes, Win: Yes, Linux: Yes. Answer: Just double them.
Example:
msgbox ”This String contains ””quotes””.”
20.0.215
How to use Sybase in Web App?
Plugin Version: all, Console & Web: No, Mac: Yes, Win: Yes, Linux: Yes. Answer: Please use our MBS
Real Studio SQL Plugin to connect to a Sybase Database in your web application.
Notes:
If you see db.Connect giving the error message ”cs ctx alloc ->CS MEM ERROR”, than some things are
not setup right for Sybase.
The Apache process may not have all the SYBASE environment variables being set when the CGI was
launched.
Adding these lines to /etc/httpd/conf/httpd.conf stopped the faux memory errors for us:
SetEnv LD LIBRARY PATH /opt/sybase/OCS-15 0/lib:/opt/sybase/OCS-15 0/lib3p64:/opt/sybase/OCS-15 0/lib3p:
SetEnv SYBROOT /opt/sybase
SetEnv SYBASE OCS /opt/sybase
613
SetEnv SYBASE /opt/sybase
20.0.216
How to use the Application Support folder?
Plugin Version: all, Console & Web: No, Mac: Yes, Win: No, Linux: No. Answer:
I was saving a registration code for an app to the Preferencefolder.
People on the list have suggested that it would be better in
the ApplicationSupportFolder. How do I save the file called CWWPrefs
into that folder using MBS?
I have checked for examples and the docs but can’t see how to apply it
//f = SpecialFolder.Preferences.child(”CWWPrefs”)
f = ApplicationSupportFolderMBS(-32768)
Example:
dim folder,file as FolderItem
folder = createApplicationSupportFolderMBS(-32763)
if folder=nil then
// Some very old Mac OS Versions may not support it
// or the plugin may fail for any reason
folder=SpecialFolder.Preferences
end if
file=folder.Child(”CWWPrefs”)
MsgBox file.UnixpathMBS
Notes: You may not be able to write there with a normal user account!
20.0.217
How to use the IOPMCopyScheduledPowerEvents function in Realbasic?
Plugin Version: all, Console & Web: No, Mac: Yes, Win: No, Linux: No. Answer: You can use the
following code which does this using the SoftDeclareMBS class.
Example:
Sub Open()
dim c as CFDateMBS
614
CHAPTER 20. THE FAQ
dim t as CFAbsoluteTimeMBS
// get current date
c=NewCFDateMBS
// in absolute time (seconds since x)
t=c.AbsoluteTime
// add 600 seconds (= 10 Minutes)
t.Value=t.Value+600
// Make a Date from it
c=t.Date
// Schedule the event
// 0 on success
// E00002C1 for missing root rights
Title=hex(schedulePowerEvent(c, ”wake”))
// Just for information, display the scheduled stuff
CFShowMBS CopyScheduledPowerEvents
End Sub
Function CopyScheduledPowerEvents() As cfarrayMBS
dim s as SoftDeclareMBS
dim m as MemoryBlock
s=new SoftDeclareMBS
if s.LoadLibrary(”IOKit.framework”) then
if s.LoadFunction(”IOPMCopyScheduledPowerEvents”) then
if s.CallFunction(0,nil) then
Return NewCFArrayMBSHandle(s.Result,true)
else
MsgBox ”Failed to Call IOPMCopyScheduledPowerEvents.”
end if
else
MsgBox ”Failed to load IOPMCopyScheduledPowerEvents.”
end if
else
MsgBox ”Failed to load IOKit.”
end if
Return nil
End Function
Function SchedulePowerEvent(time to wake as CFDateMBS, Type as CFStringMBS) as Integer
dim s as SoftDeclareMBS
615
dim m as MemoryBlock
’/*
’* Types of power event
’* These are potential arguments to IOPMSchedulePowerEvent().
’* These are all potential values of the kIOPMPowerEventTypeKey in the CFDictionaries
’* returned by IOPMCopyScheduledPowerEvents().
’*/
’/*!
’@define kIOPMAutoWake
’@abstract Value for scheduled wake from sleep.
’*/
’# define kIOPMAutoWake ”wake”
’
’/*!
’@define kIOPMAutoPowerOn
’@abstract Value for scheduled power on from off state.
’*/
’# define kIOPMAutoPowerOn ”poweron”
’
’/*!
’@define kIOPMAutoWakeOrPowerOn
’@abstract Value for scheduled wake from sleep, or power on. The system will either wake OR
’power on, whichever is necessary.
’*/
’
’# define kIOPMAutoWakeOrPowerOn ”wakepoweron”
’/*!
’@define kIOPMAutoSleep
’@abstract Value for scheduled sleep.
’*/
’
’# define kIOPMAutoSleep ”sleep”
’/*!
’@define kIOPMAutoShutdown
’@abstract Value for scheduled shutdown.
’*/
’
’# define kIOPMAutoShutdown ”shutdown”
s=new SoftDeclareMBS
if s.LoadLibrary(”IOKit.framework”) then
if s.LoadFunction(”IOPMSchedulePowerEvent”) then
m=NewMemoryBlock(12)
m.Long(0)=time to wake.handle
m.Long(4)=0 // nil
616
CHAPTER 20. THE FAQ
m.Long(8)=type.Handle
if s.CallFunction(3,m) then
Return s.Result
end if
end if
end if
End Function
Notes: Requires Mac OS X and to execute root rights.
20.0.218
How to validate a GUID?
Plugin Version: all, Console & Web: No, Mac: Yes, Win: Yes, Linux: Yes. Answer: You can use this
function below which uses a regular expression to verify that the string is a valid UUID/GUID:
Example:
Function IsGUID(guid as string) As Boolean
dim r as new RegEx
r.SearchPattern = ”ˆ(\{ { 0,1 } ( [ 0-9a-fA-F ] ) { 8 } -( [ 0-9a-fA-F ] ) { 4 } -( [ 0-9a-fA-F ] ) { 4 }
-( [ 0-9a-fA-F ] ) { 4 } -( [ 0-9a-fA-F ] ) { 12 } \} { 0,1 } )$ ”
Return r.Search(guid)<>nil
End Function
Notes: Simply parsing the GUID with CFUUIDMBS does not give the same result as CFUUIDMBS will
also take a string like ”DDDD”.
20.0.219
How to walk a folder hierarchie non recursively?
Plugin Version: all, Console & Web: No, Mac: Yes, Win: Yes, Linux: Yes. Answer: Use code like this one:
Example:
Sub Walk(folder as FolderItem)
dim folders() as FolderItem
folders.Append folder
while UBound(folders)>=0
617
dim currentFolder as FolderItem = folders.pop
dim c as Integer = currentFolder.Count
for i as Integer = 1 to c
dim item as FolderItem = currentFolder.TrueItem(i)
if item = Nil then
// no permission
elseif item.Visible then // only visible
if item.Directory then
folders.Append item
else
// work with file here
end if
end if
next
wend
End Sub
Notes:
As you see we go with a long loop which runs until we don’t have more folders to process.
We ignore items we can’t access due to permission limits.
And we only work visible items.
If you like, check folderitem.isBundleMBS on item to handle packages and applications better on Mac OS
X.
20.0.220
I got this error: PropVal, QDPictMBS.Name (property value), Type
mismatch error. Expected CGDataProviderMBS, but got Variant,
Name:QDPictMBS
Plugin Version: all, Console & Web: No, Mac: Yes, Win: No, Linux: No. Answer: The plugins MacOSX
and MacOSXCF belong together. If you use one part, please also install the other part.
Notes: We splitted the plugin because the Real Studio IDE on Windows crashed on compilation.
618
20.0.221
CHAPTER 20. THE FAQ
I registered the MBS Plugins in my application, but later the registration dialog is shown.
Plugin Version: all, Console & Web: No, Mac: Yes, Win: Yes, Linux: Yes. Answer: There are two main
reasons.
Notes:
1. you may use the plugin before registering them. This is often the case if you register in a window open
event and use the plugin in a control open event.
On the console on Mac OS X or Windows, you may see a message like this ”MBS Plugins were used by the
application before the RegisterMBSPlugin function was called. Please fix this in your code!”.
2. you may have mixed different plugin versions which are not compatible.
In this case you can see a message ”Internal plugin registration error.” on the console on Mac OS X. Newer
plugins may show a message dialog reporting this. Older version simply think they are not registered.
If the installer just merges old and new applications, users may have libraries of older and newer plugin
versions in the libs folder. If your application loads the wrong version, the registration fails.
If you use remote debugging, make sure you clear the tempory files there, too. Otherwise you may have old
DLLs on your hard disc which may disturb your application.
You can run into issues if you use your registration code on different places of your app. Please register only
once in app.open (or app Constructor). If you have several codes, simply call them one after the other.
Also check that you only call RegisterMBSPlugin with valid serial number. If you later call RegisterMBSPlugin with Demo like in example code above, you remove the license.
Finally make sure you use the right serial number. Not an older one or a misspelled one.
20.0.222
I want to accept Drag & Drop from iTunes
Plugin Version: all, Console & Web: No, Mac: Yes, Win: No, Linux: No. Answer: You need to accept
AcceptMacDataDrop ”itun” and Handle the DropObject.
Example:
Sub Open()
window1.AcceptMacDataDrop ”itun”
End Sub
Sub DropObject(obj As DragItem)
dim s as string
dim f as folderItem
619
dim
dim
dim
dim
dim
dim
dim
d as CFDictionaryMBS
o as CFObjectMBS
key as CFStringMBS
dl as CFDictionaryListMBS
i,c as Integer
u as CFURLMBS
file as FolderItem
if obj.MacDataAvailable(”itun”) then
s = obj.MacData(”itun”)
// Parse XML
o=NewCFObjectMBSFromXML(NewCFBinaryDataMBSStr(s))
// Make dictionary
if o isa CFDictionaryMBS then
d=CFDictionaryMBS(o)
// get Tracks Dictionary
key=NewCFStringMBS(”Tracks”)
o=d.Value(key)
if o isa CFDictionaryMBS then
d=CFDictionaryMBS(o)
dl=d.List
// Walk over all entries in the Tracks dictionary
c=dl.Count-1
for i=0 to c
o=dl.Value(i)
if o isa CFDictionaryMBS then
d=CFDictionaryMBS(o)
key=NewCFStringMBS(”Location”)
o=d.Value(key)
if o isa CFStringMBS then
u=NewCFURLMBSCFStringMBS(CFStringMBS(o),nil)
file=u.file
if file<>nil then
MsgBox file.UnixpathMBS
end if
end if
end if
next
end if
end if
620
CHAPTER 20. THE FAQ
end if
End Sub
Notes: The code above inside a window on Realbasic 5.5 with MBS Plugin 5.3 will do it nice and show the
paths.
20.0.223
I’m drawing into a listbox but don’t see something.
Plugin Version: all, Console & Web: No. Answer: If you draw this in a listbox cellbackground, you need
to draw on the correct position
Example:
Function CellBackgroundPaint(g As Graphics, row as Integer, column as Integer) As Boolean
dim f as FolderItem
f=SpecialFolder.Desktop
f.DrawWideIconMBS(g,listbox1.left,listbox1.top+row*20,16)
Return true
End Function
Notes: Try this in a listbox. The Graphics object there has a cliping and an offset which the plugin doesn’t
know about.
20.0.224
I’m searching for a method or so to move a window from position x.y
to somewhere else on the screen.
Console & Web: No, Mac: Yes, Win: No, Linux: No. Answer:
The code I produced in RB isn’t smooth enough. Is there a call in MBS, if not, can it be done? The speed
of it has to be like the show of a DrawerWindow.
Try the declare below for Carbon. With WindowLib it will work on Mac OS 8.5 and newer.
Notes: See Window.Transition functions.
621
20.0.225
If I use one of your plug-ins under windows, would this then impose
the use of dll after compilation or my would my compiled soft still be
a stand-alone single file software?
Console & Web: No, Mac: Yes, Win: Yes, Linux: Yes. Answer: Stand alone.
Notes:
REALbasic compiles all used plugins into the application binary.
Some plugin parts need external dlls but you will find that in the documentation. (e.g. pdflib for some classes)
20.0.226
Is the fn key on a powerbook keyboard down?
Plugin Version: all, Console & Web: No, Mac: Yes, Win: No, Linux: No. Answer: I am unable to figure
out how or if it is possible to detect if the fn key is down on a powerbook keyboard. Is it possible?
Example:
’ Window.Open Event of a blank project:
dim i as Integer
for i=0 to 127
if keyboard.asynckeydown(i) then
title=str(i) // found
return
end if
next
title=”” // not found
Notes: This test application shows the keycode (decimal) 63 for the fn key.
20.0.227
Is there a case sensitive Dictionary?
Plugin Version: all, Console & Web: No. Answer: The MBS Plugin has several classes which can work as
a replacement.
Notes:
First you could use VariantToVariantHashMapMBS or VariantToVariantOrderedMapMBS.
If you know that all keys are Strings or Integers only, you can use the specialized classes which are a little
bit faster due to avoiding variants:
IntegerToIntegerHashMapMBS class
IntegerToIntegerOrderedMapMBS class
622
CHAPTER 20. THE FAQ
IntegerToStringHashMapMBS class
IntegerToStringOrderedMapMBS class
IntegerToVariantHashMapMBS class
IntegerToVariantOrderedMapMBS class
StringToStringHashMapMBS class
StringToStringOrderedMapMBS class
StringToVariantHashMapMBS class
StringToVariantOrderedMapMBS class
20.0.228
Is there a way to use the MBS plugin to get only the visible item and
folder count on a volume?
Plugin Version: all, Console & Web: No, Mac: Yes, Win: Yes, Linux: Yes. Answer: You can use the
DirectorySizeMBS class for this as in the example below:
Example:
dim d as DirectorySizeMBS
d=new DirectorySizeMBS
// volume(1) as my boot volume is very full
if d.update(volume(1),true,0) then
MsgBox str(d.VisibleItemCount)+” visible items, ”+str(d.HiddenItemCount)+” invisible items.”
end if
Notes:
Complete Question: Is there a way to use the MBS plugin to get only the visible item and folder count on
a volume? The FileCount and FolderCount properties of
VolumeInformationMBS seem to provide the total # of items including
invisible items such as .DS Store and more importantly .Trashes which
is causing me a great amount of difficulty during a recursive scan of a
volume. I’ve got a progress bar which uses the total of the filecount
and foldercount properties as the maximum value, but my routine needs
to filter out all invisible items, as it is creating a catalog of a
volume for archiving purposes. Any thoughts how I could get accurate
number.
20.0.229
Is there an easy way I can launch the Displays preferences panel?
Plugin Version: all, Console & Web: No, Mac: Yes, Win: No, Linux: No. Answer: Use the code below:
Example:
623
dim error as Integer
error=OpenMacOSXPreferencesPaneMBS(”Displays”)
if error<>0 then
MsgBox ”Failed to launch QuickTime System Preferences panel.”
end if
20.0.230
Is there an easy way I can launch the Quicktime preferences panel?
Plugin Version: all, Console & Web: No, Mac: Yes, Win: No, Linux: No. Answer: Use the code below:
Example:
dim error as Integer
error=OpenMacOSXPreferencesPaneMBS(”QuickTime”)
if error<>0 then
MsgBox ”Failed to launch QuickTime System Preferences panel.”
end if
20.0.231
List of Windows Error codes?
Plugin Version: all, Console & Web: No, Mac: Yes, Win: Yes, Linux: Yes. Answer: We have a list of
windows error codes on our website.
Notes: http://www.monkeybreadsoftware.de/xojo/winerror.shtml
20.0.232
Midi latency on Windows problem?
Plugin Version: all, Console & Web: No, Mac: Yes, Win: Yes, Linux: Yes. Answer: The issue is system
related, not a problem with RB or the plugin.
Notes:
Two things will adversely affect the timing:
(1) latency of the software synthesizer output driver. The default Windows wavetable synthesizer has considerable latency. I don’t know how many milliseconds, but it is noticeable.
(2) latency of the digital audio output driver. Different systems have different drivers for different audio
hardware. My Dell laptop has a minimum 15ms latency in the audio driver.
624
CHAPTER 20. THE FAQ
These two things put together were causing a very sluggish MIDI response. I was able to verify these as the
culprits by routing MIDI directly out of RB into a sample player, which only introduces the latency of (2)
and does not include latency of (1).
I don’t know how widely known are these facts, if not then you may want to add this information to the
documentation, since Windows programmers using the MIDI plugin may not know those problems, and
might mistakenly blame your plugin, as I did :) Sorry about that!
(From Aaron Andrew Hunt)
20.0.233
My Xojo Web App does not launch. Why?
Plugin Version: all, Console & Web: No, Mac: Yes, Win: No, Linux: No. Answer: Here is a list of checks
to do for linux apache installations with Xojo or Real Studio Web applications:
Notes:
Just a list of checks to do for linux apache installations:
• You have 64bit linux? Than you need 32 bit compatibility libraries.
• The folder of your app is writable? Set permissions to 777.
• The cgi script is executable? Set permissions to 755.
• The app file itself is executable? Set permissions to 755.
• You uploaded cgi file as text, so it has unix line endings? (this often gives error ”Premature end of
script headers” in apache log)
• You uploaded config.cfg file and made it writable? Set permissions to 666.
• Your apache allows execution of cgi scripts? You enabled cgi for apache and uncommented addhandler
command for CGI on a new apache installation?
• You uploaded the app file and libraries as binary files? Upload as text breaks them.
• You did upload the libs folder?
• You don’t have code in app.open, session.open and other events which crashes app right at launch?
• You don”t have a print command in your app.open event? (see feedback case 23817)
• You allowed htaccess file to overwrite permissions?
625
20.0.234
Pictures are not shown in my application. Why?
Plugin Version: all, Console & Web: No, Mac: Yes, Win: Yes, Linux: No. Answer:
On Mac OS Classic, please check the memory partition size which may be too low.
Else (most times on Windows) you are simple missing the part of QuickTime to load images.
20.0.235
Realbasic doesn’t work with your plugins on Windows 98.
Plugin Version: all, Console & Web: No, Mac: No, Win: Yes, Linux: No. Answer: Upgrade your Windows
version or complain to Realsoftware.
20.0.236
REALbasic or my RB application itself crashes on launch on Mac OS
Classic. Why?
Plugin Version: all, Console & Web: No. Answer:
You may check if the application has enough memory to be loaded.
RB should have on Mac OS Classic more than 20 MB of RAM.
I prefered to use 50 MB and for an application a 10 MB partition is a good way to start.
20.0.237
SQLDatabase not initialized error?
Plugin Version: all, Console & Web: No, Mac: Yes, Win: Yes, Linux: Yes. Answer: Before you can use
SQLDatabaseMBS, it must be initialized.
Example:
dim d as new SQLDatabaseMBS
Notes:
This happens normally when you use ”new SQLDatabaseMBS”.
But if you just have a SQLConnectionMBS and get a recordset there, the initialization may not have happend, yet.
So please simply add a line ”dim d as new SQLDatabaseMBS” to your app.open code after registration, so
the plugin part can initialize and late provide recordsets.
20.0.238
Textconverter returns only the first x characters. Why?
Plugin Version: all, Console & Web: No, Mac: Yes, Win: Yes, Linux: Yes. Answer:
626
CHAPTER 20. THE FAQ
Some older REALbasic versions limit the Textconverter to around 1024 characters in input and output.
This should be fixed with RB5.
Notes: REALbasic seems not to support Textconverters at all on Windows.
20.0.239
The type translation between CoreFoundation/Foundation and Realbasic data types.
Plugin Version: all, Console & Web: No, Mac: Yes, Win: No, Linux: No. Answer: The plugin does
conversion between Cocoa/Carbon data types and native REALbasic data types. The following list help you
knowing what the current plugins support:
Notes:
Cocoa NSObject to Variant:
nil ->nil
NSDictionary ->Dictionary
NSData ->MemoryBlock
NSString ->String
NSAttributedString ->NSAttributedStringMBS
NSDate ->Date
NSNumber ->double/integer/Int64/UInt64/UInt32/Boolean
NSURL ->String
NSValue with NSRect ->NSRectMBS
NSValue with NSPoint ->NSPointMBS
NSValue with NSSize ->NSSizeMBS
NSValue with NSRange ->NSRangeMBS
NSValue with QTTime ->QTTimeMBS
NSValue with QTTimeRange ->QTTimeRangeMBS
NSArray ->Array of Variant
QuartzFilter ->QuartzFilterMBS
• ->*MBS
Variant to Cocoa NSObject:
nil ->nil
Dictionary ->NSDictionary
Boolean ->NSNumber
Integer ->NSNumber
Color ->NSColor
Int64 ->NSNumber
Single ->NSNumber
Double ->NSNumber
Date ->NSDate
627
MemoryBlock ->NSData
String ->NSString
NSImageMBS ->NSImage
NSAttributedStringMBS ->NSAttributedString
NSColorMBS ->NSColor
NSRectMBS ->NSValue with NSRect
NSSizeMBS ->NSValue with NSSize
NSPointMBS ->NSValue with NSPoint
NSRangeMBS ->NSValue with NSRange
NSBurnMBS ->NSBurn
NSViewMBS ->NSView
NSFontMBS ->NSFont
NSParagraphStyleMBS ->NSParagraphStyle
NSAttributedStringMBS ->NSAttributedString
WebPolicyDelegateMBS ->WebPolicyDelegate
WebUIDelegateMBS ->WebUIDelegate
WebFrameLoadDelegateMBS ->WebFrameLoadDelegate
WebResourceLoadDelegateMBS ->WebResourceLoadDelegate
NSIndexSetMBS ->NSIndexSet
QTTimeMBS ->QTTime
QTTimeRangeMBS ->QTTimeRange
Array of Variant ->NSArray
Array of String ->NSArray
CFStringMBS ->NSString
CFNumberMBS ->NSNumber
CFDataMBS ->NSData
CFURLMBS ->NSURL
CFArrayMBS ->NSArray
CFDictionaryMBS ->NSDictionary
CFBinaryDataMBS ->NSDate
Carbon CFTypeRef to Variant:
CFDictionaryRef ->Dictionary
CFStringRef ->String
CFDataRef ->String
CFURL ->String
CFNumber ->Integer/Double/Int64
CFArray ->Array
CFDate ->date
nil ->nil
CGColorSpace ->CGColorSpaceMBS
CGColor ->CGColorMBS
CGImage ->CGImageMBS
CF* ->CF*MBS
628
CHAPTER 20. THE FAQ
Variant to Carbon CFTypeRef:
Dictionary ->CFDictionaryRef
Boolean ->CFBooleanRef
Color ->CFNumberRef
Integer ->CFNumberRef
Int64 ->CFNumberRef
Single ->CFNumberRef
Double ->CFNumberRef
String ->CFStringRef
Color ->CGColorRef
Date ->CFDateRef
nil ->nil
Memoryblock ->CFDataRef
Folderitem ->CFURLRef
Dictionary ->CFDictionaryRef
Array of Variant/String/Date/Double/Single/Int64/Integer ->CFArray
CGRectMBS ->CGRect as CFDataRef
CGSizeMBS ->CGSize as CFDataRef
CGPointMBS ->CGPoint as CFDataRef
CGColorMBS ->CGColor
CGColorSpaceMBS ->CGColorSpace
CGImageMBS ->CGImage
CGDataConsumerMBS ->CGDataConsumer
CGDataProviderMBS ->CGDataProvider
CF*MBS ->CF*
Strings without encodings should be put into dictionaries as memoryblocks.
20.0.240
Uploaded my web app with FTP, but it does not run on the server!
Plugin Version: all, Console & Web: No, Mac: No, Win: Yes, Linux: No. Answer: If you see errors like a
simple ”Segmentation Fault” on Linux or some other wired errors, you may want to check your FTP upload
mode. It must be binary for web apps. ASCII mode corrupts the application.
20.0.241
What classes to use for hotkeys?
Plugin Version: all, Console & Web: No, Mac: Yes, Win: Yes, Linux: Yes. Answer: Please use CarbonHotKeyMBS class on Mac and WindowsKeyFilterMBS on Windows.
Notes: CarbonHotKeyMBS will also work fine in Cocoa apps.
629
20.0.242
What do I need for Linux to get picture functions working?
Plugin Version: all, Console & Web: No, Mac: Yes, Win: Yes, Linux: Yes. Answer: In order to get our
plugins working on Linux systems without GUI, the plugin loads graphics libraries dynamically.
Notes:
To get it working, the plugin tries to load gtk with this paths:
• libgtk-x11-2.0.so”
• libgtk-x11-2.0.so.0”
• /usr/lib/libgtk-x11-2.0.so”
• /usr/lib32/libgtk-x11-2.0.so”
• /usr/lib/libgtk-x11-2.0.so.0”
• /usr/lib32/libgtk-x11-2.0.so.0”
gdk is loaded with this paths:
• libgdk-x11-2.0.so”
• libgdk-x11-2.0.so.0”
• /usr/lib/libgdk-x11-2.0.so”
• /usr/lib32/libgdk-x11-2.0.so”
• /usr/lib/libgdk-x11-2.0.so.0”
• /usr/lib32/libgdk-x11-2.0.so.0”
For the paths without explicit path, the system will search in /lib, /usr/lib and all directories in the
LD LIBRARY PATH environment variable.
20.0.243
What does the NAN code mean?
Plugin Version: all, Console & Web: No, Mac: Yes, Win: Yes, Linux: Yes. Answer:
630
20.0.244
CHAPTER 20. THE FAQ
What font is used as a ’small font’ in typical Mac OS X apps?
Plugin Version: all, Console & Web: No, Mac: Yes, Win: No, Linux: No. Answer:
REALbasic 4.5 has a constant ”SmallSystem” to use for a font name.
For older versions try this code:
Example:
Sub GetThemeFont(fontType as Integer, ByRef fontName as String, ByRef fontSize as Integer, ByRef
fontStyle as Integer)
dim err as Integer
dim theFont, theFontSize, theFontStyle as MemoryBlock
const smSystemScript = -1
Declare Function GetThemeFont Lib ”Carbon” (inFontID as Integer, inScript as Integer, outFontName
as Ptr, outFontSize as Ptr, outStyle as Ptr) as Integer
theFont = NewMemoryBlock(256) //Str255
theFontSize = NewMemoryBlock(2) //SInt16
theFontStyle = NewMemoryBlock(1) //Style
err = GetThemeFont(fontType, smSystemScript, theFont, theFontSize, theFontStyle)
if err = 0 then
fontName = theFont.PString(0)
fontSize = theFontSize.UShort(0)
fontStyle = theFontStyle.Byte(0)
else
fontName = ””
fontSize = 0
fontStyle = 0
end if
End Sub
20.0.245
What is last plugin version to run on Mac OS X 10.4?
Plugin Version: all, Console & Web: No, Mac: No, Win: Yes, Linux: No. Answer: Last Version with 10.4
support is version 15.4.
Notes:
With version 15.4 you can build applications for OS X 10.4 and newer.
For Version 16.0 we disabled 10.4 and moved minimum to 10.5. We may be able to enable it again to build
a version of 16.x, but may need to charge for this by hour.
631
20.0.246
What is last plugin version to run on PPC?
Plugin Version: all, Console & Web: No, Mac: No, Win: Yes, Linux: No. Answer: Last Version with PPC
is 15.4.
Notes:
With version 15.4 you can build PPC applications for OS X 10.4 and newer.
For Version 16.0 we disabled PPC. We may be able to enable it again to build a PPC version of 16.x, but
may need to charge for this by hour.
20.0.247
What is the difference between Timer and WebTimer?
Plugin Version: all, Console & Web: No, Mac: Yes, Win: Yes, Linux: Yes. Answer: Time is server side
and WebTimer client side.
Notes: Timer is the normal timer class in Real Studio. It runs on the server. On the side the WebTimer
runs on the client. It triggers a request to the server to perform the action. So a WebTimer is good to keep
the connection running and the website updated regularly. A timer on the server is good to make regular
jobs like starting a database backup every 24 hours.
20.0.248
What is the list of Excel functions?
Plugin Version: all, Console & Web: No, Mac: Yes, Win: Yes, Linux: Yes. Answer: Below a list of function
names known by LibXL.
Notes:
LibXL parses the functions and writes tokens to the excel file. So even if Excel can do more functions, we
can only accept the ones known by LibXL.
ABS, ABSREF, ACOS, ACOSH, ACTIVE.CELL, ADD.BAR, ADD.COMMAND, ADD.MENU, ADD.TOOLBAR, ADDRESS, AND, APP.TITLE, AREAS, ARGUMENT, ASC, ASIN, ASINH, ATAN, ATAN2, ATANH,
AVEDEV, AVERAGE, AVERAGEA, BAHTTEXT, BETADIST, BETAINV, BINOMDIST, BREAK, CALL,
CALLER, CANCEL.KEY, CEILING, CELL, CHAR, CHECK.COMMAND, CHIDIST, CHIINV, CHITEST,
CHOOSE, CLEAN, CODE, COLUMN, COLUMNS, COMBIN, CONCATENATE, CONFIDENCE, CORREL, COS, COSH, COUNT, COUNTA, COUNTBLANK, COUNTIF, COVAR, CREATE.OBJECT, CRITBINOM, CUSTOM.REPEAT, CUSTOM.UNDO, DATE, DATEDIF, DATESTRING, DATEVALUE, DAVERAGE, DAY, DAYS360, DB, DBCS, DCOUNT, DCOUNTA, DDB, DEGREES, DELETE.BAR, DELETE.COMMAND, DELETE.MENU, DELETE.TOOLBAR, DEREF, DEVSQ, DGET, DIALOG.BOX, DIRECTORY,
DMAX, DMIN, DOCUMENTS, DOLLAR, DPRODUCT, DSTDEV, DSTDEVP, DSUM, DVAR, DVARP,
ECHO, ELSE, ELSE.IF, ENABLE.COMMAND, ENABLE.TOOL, END.IF, ERROR, ERROR.TYPE, EVALUATE, EVEN, EXACT, EXEC, EXECUTE, EXP, EXPONDIST, FACT, FALSE, FCLOSE, FDIST, FILES,
FIND, FINDB, FINV, FISHER, FISHERINV, FIXED, FLOOR, FOPEN, FOR, FOR.CELL, FORECAST,
FORMULA.CONVERT, FPOS, FREAD, FREADLN, FREQUENCY, FSIZE, FTEST, FV, FWRITE, FWRITELN,
GAMMADIST, GAMMAINV, GAMMALN, GEOMEAN, GET.BAR, GET.CELL, GET.CHART.ITEM,
GET.DEF, GET.DOCUMENT, GET.FORMULA, GET.LINK.INFO, GET.MOVIE, GET.NAME, GET.NOTE,
632
CHAPTER 20. THE FAQ
GET.OBJECT, GET.PIVOT.FIELD, GET.PIVOT.ITEM, GET.PIVOT.TABLE, GET.TOOL, GET.TOOLBAR, GET.WINDOW, GET.WORKBOOK, GET.WORKSPACE, GETPIVOTDATA, GOTO, GROUP,
GROWTH, HALT, HARMEAN, HELP, HLOOKUP, HOUR, HYPERLINK, HYPGEOMDIST, IF, INDEX, INDIRECT, INFO, INITIATE, INPUT, INT, INTERCEPT, IPMT, IRR, ISBLANK, ISERR, ISERROR, ISLOGICAL, ISNA, ISNONTEXT, ISNUMBER, ISPMT, ISREF, ISTEXT, ISTHAIDIGIT, KURT,
LARGE, LAST.ERROR, LEFT, LEFTB, LEN, LENB, LINEST, LINKS, LN, LOG, LOG10, LOGEST,
LOGINV, LOGNORMDIST, LOOKUP, LOWER, MATCH, MAX, MAXA, MDETERM, MEDIAN, MID,
MIDB, MIN, MINA, MINUTE, MINVERSE, MIRR, MMULT, MOD, MODE, MONTH, MOVIE.COMMAND, N, NA, NAMES, NEGBINOMDIST, NEXT, NORMDIST, NORMINV, NORMSDIST, NORMSINV, NOT, NOTE, NOW, NPER, NPV, NUMBERSTRING, ODD, OFFSET, OPEN.DIALOG, OPTIONS.LISTS.GET, OR, PAUSE, PEARSON, PERCENTILE, PERCENTRANK, PERMUT, PHONETIC,
PI, PIVOT.ADD.DATA, PMT, POISSON, POKE, POWER, PPMT, PRESS.TOOL, PROB, PRODUCT,
PROPER, PV, QUARTILE, RADIANS, RAND, RANK, RATE, REFTEXT, REGISTER, REGISTER.ID,
RELREF, RENAME.COMMAND, REPLACE, REPLACEB, REPT, REQUEST, RESET.TOOLBAR, RESTART,
RESULT, RESUME, RETURN, RIGHT, RIGHTB, ROMAN, ROUND, ROUNDBAHTDOWN, ROUNDBAHTUP, ROUNDDOWN, ROUNDUP, ROW, ROWS, RSQ, RTD, SAVE.DIALOG, SAVE.TOOLBAR,
SCENARIO.GET, SEARCH, SEARCHB, SECOND, SELECTION, SERIES, SET.NAME, SET.VALUE,
SHOW.BAR, SIGN, SIN, SINH, SKEW, SLN, SLOPE, SMALL, SPELLING.CHECK, SQRT, STANDARDIZE, STDEV, STDEVA, STDEVP, STDEVPA, STEP, STEYX, SUBSTITUTE, SUBTOTAL, SUM, SUMIF,
SUMPRODUCT, SUMSQ, SUMX2MY2, SUMX2PY2, SUMXMY2, SYD, T, TAN, TANH, TDIST, TERMINATE, TEXT, TEXT.BOX, TEXTREF, THAIDAYOFWEEK, THAIDIGIT, THAIMONTHOFYEAR,
THAINUMSOUND, THAINUMSTRING, THAISTRINGLENGTH, THAIYEAR, TIME, TIMEVALUE,
TINV, TODAY, TRANSPOSE, TREND, TRIM, TRIMMEAN, TRUE, TRUNC, TTEST, TYPE, UNREGISTER, UPPER, USDOLLAR, USERDEFINED, VALUE, VAR, VARA, VARP, VARPA, VDB, VIEW.GET,
VLOOKUP, VOLATILE, WEEKDAY, WEIBULL, WHILE, WINDOW.TITLE, WINDOWS, YEAR and
ZTEST.
20.0.249
What is the replacement for PluginMBS?
Plugin Version: all, Console & Web: No, Mac: Yes, Win: No, Linux: No. Answer: Use the SoftDeclareMBS
class to load libraries dynamically.
20.0.250
What to do on Realbasic reporting a conflict?
Plugin Version: all, Console & Web: No, Mac: Yes, Win: Yes, Linux: Yes. Answer:
I get an error like ”This item conflicts with another item of the same name” when using one of the plugin
functions.
REALbasic just wants to tell you that you dropped something in the plugins folder what is not a plugin.
Notes: Some users dropped the examples, the documentation or other files into the plugins folder. Don’t
do it.
633
20.0.251
What to do with a NSImageCacheException?
Plugin Version: all, Console & Web: No, Mac: Yes, Win: Yes, Linux: No. Answer: You need to add
exception handlers for NSExceptionMBS in order to catch this exception.
Notes:
You may also add code to write the stack of the exception into a log file for later locating the error source.
A NSImage has several image representations in memory. So basicly you pass in the base image and for
whatever size an image is needed, the NSImage class will create a cache image representation of the requested
size so on the next query it can use that cache for the same requested size.
20.0.252
What to do with MySQL Error 2014?
Plugin Version: all, Console & Web: No, Mac: Yes, Win: Yes, Linux: Yes. Answer: You can get this error
on MySQL if you have a recordset open while you create another one.
20.0.253
What ways do I have to ping?
Plugin Version: all, Console & Web: No, Mac: Yes, Win: Yes, Linux: No. Answer: You have different
ways
Notes:
1. Use the shell class and the ping utility.
2. Use the MBS Network Plugin and there the SuperSocket part:
a) On Windows the ICMPPingMBS works to ping.
b) On Mac OS X it uses OpenTransport and needs root rights. You need to use sudo to run this application.
This does not work on Intel Macs, because the plugin is not endian safe.
3. The DarwinPingMBS.Ping method:
Compiled for Mac OS X Macho target it works as a syncronized ping method.
The Windows version had a bug and was fixed in plugin version 8.2pr4. So it works now.
4. The DarwinPingMBS.SimplePing method:
Works on Mac OS X Macho target.
634
CHAPTER 20. THE FAQ
But this method can be called from a thread to make it working in background.
20.0.254
Where is CGGetActiveDisplayListMBS?
Plugin Version: all, Console & Web: No, Mac: No, Win: Yes, Linux: No. Answer: This is now CGDisplayMBS.GetActiveDisplayList.
20.0.255
Where is CGGetDisplaysWithPointMBS?
Plugin Version: all, Console & Web: No, Mac: No, Win: Yes, Linux: No. Answer: This is now CGDisplayMBS.GetDisplaysWithPoint.
20.0.256
Where is CGGetDisplaysWithRectMBS?
Plugin Version: all, Console & Web: No, Mac: No, Win: Yes, Linux: No. Answer: This is now CGDisplayMBS.GetDisplaysWithRect.
20.0.257
Where is CGGetOnlineDisplayListMBS?
Plugin Version: all, Console & Web: No, Mac: No, Win: Yes, Linux: No. Answer: This is now CGDisplayMBS.GetOnlineDisplayList.
20.0.258
Where is GetObjectClassNameMBS?
Plugin Version: all, Console & Web: No, Mac: Yes, Win: Yes, Linux: Yes. Answer: Please use this
replacement method:
Example:
Function GetObjectClassNameMBS(o as Object) As string
dim t as Introspection.TypeInfo = Introspection.GetType(o)
Return t.FullName
End Function
Notes: GetObjectClassNameMBS was removed from the plugins.
635
20.0.259
Where is NetworkAvailableMBS?
Plugin Version: all, Console & Web: No, Mac: Yes, Win: Yes, Linux: Yes. Answer: We removed NetworkAvailableMBS some versions ago. It was not working right and basicly it’s not useful. If you want to
check whether you have a network, than do a DNS resolve:
Example:
// two independend domain names
const domain1 = ”www.google.com”
const domain2 = ”www.macsw.de”
// resolve IPs
dim ip1 as string = DNSNameToAddressMBS(Domain1)
dim ip2 as string = DNSNameToAddressMBS(Domain2)
// if we got IPs and not the same IPs (error/login pages)
if len(ip1)=0 or len(ip2)=0 or ip1=ip2 then
MsgBox ”no connection”
else
MsgBox ”have connection”
end if
Notes: This way you can detect whether you got something from DNS. And you can make sure that a DNS
redirection to a login page won’t catch you.
20.0.260
Where is StringHeight function in DynaPDF?
Plugin Version: all, Console & Web: No, Mac: No, Win: Yes, Linux: No. Answer: Use the function
GetFTextHeight or GetFTextHeightEx.
Notes: Be aware that GetFTextHeight works with format commands and you may want to escape your
text if you don’t use them.
20.0.261
Where is XLSDocumentMBS class?
Plugin Version: all, Console & Web: No, Mac: Yes, Win: No, Linux: No. Answer: This class has been
removed in favor of XLBookMBS class.
Notes: This classes have been removed XLSCellMBS, XLSDocumentMBS, XLSFormatRecordMBS, XLSMergedCellsMBS, XLSRowMBS and XLSSheetMBS.
636
20.0.262
CHAPTER 20. THE FAQ
Where to get information about file formats?
Plugin Version: all, Console & Web: No, Mac: Yes, Win: Yes, Linux: Yes. Answer:
Please visit this web page:
http://www.wotsit.org
20.0.263
Where to register creator code for my application?
Plugin Version: all, Console & Web: No, Mac: Yes, Win: No, Linux: No. Answer:
Register at Apple:
http://developer.apple.com/dev/cftype/information.html
20.0.264
Which Mac OS X frameworks are 64bit only?
Plugin Version: all, Console & Web: No, Mac: Yes, Win: No, Linux: No. Answer: Some frameworks from
Mac OS X do not support 32 bit applications, so we can’t provide plugins for Xojo until 64bit target is
available.
Notes:
For Mac OS X 10.8:
• Accounts
• EventKit
• GLKit
• Social
and in 10.9:
• Accounts
• AVKit
• EventKit
• GameController
• GLKit
• MapKit
637
• MediaLibrary
• Social
• SpriteKit
In general Apple makes all new frameworks being 64 bit only.
20.0.265
Which plugins are 64bit only?
Plugin Version: all, Console & Web: No, Mac: Yes, Win: No, Linux: No. Answer: Some of our plugins
work only in 64 bit modes as operation systems do not provide 32 bit code.
Notes: This effects currently: EventKit, Accounts, Social frameworks from Apple and our matching plugins.
20.0.266
Why application doesn’t launch because of a missing ddraw.dll!?
Plugin Version: all, Console & Web: No, Mac: No, Win: Yes, Linux: No. Answer: Some RB versions
require that you install DirectX from Microsoft on your Windows.
20.0.267
Why application doesn’t launch because of a missing shlwapi.dll!?
Plugin Version: all, Console & Web: No, Mac: No, Win: Yes, Linux: No. Answer: Some RB versions
require that you install the Internet Explorer from Microsoft on your Windows.
Notes: This bug is for several older Windows 95 editions.
20.0.268
Why do I hear a beep on keydown?
Plugin Version: all, Console & Web: No, Mac: No, Win: Yes, Linux: No. Answer: When the user presses
a key, RB goes through all keydown event handlers till on returns true.
Notes: If no keydown event handler returns true for the key, a beep is performed.
20.0.269
Why does folderitem.item return nil?
Plugin Version: all, Console & Web: No, Mac: Yes, Win: Yes, Linux: Yes. Answer: Because Realbasic
fails to make a folderitem for you. Reason may be an alias file which can’t be resolved or simply that you
don’t have enough access rights to read the folder content.
Notes: A more rarely reason is that the directory changed and the file with the given index or name does
no longer exist.
638
20.0.270
CHAPTER 20. THE FAQ
Why doesn’t showurl work?
Plugin Version: all, Console & Web: No, Mac: Yes, Win: Yes, Linux: Yes. Answer:
There are three main reasons:
1. showurl is not supported by REALbasic in 68k applications.
2. there is now application defined for the protocol (e.g. http) in the Internet Control panel.
3. You don’t have Internet Config installed.
You can use the InternetConfigMBS class to check for this stuff.
20.0.271
Why have I no values in my chart?
Plugin Version: all, Console & Web: No, Mac: Yes, Win: Yes, Linux: No. Answer: You have no data
points visible, there may be several reasons:
Notes:
For example one of the data values may be infinite or invalid.
Or the scaling may be out of range, so you simply see nothing.
20.0.272
Will application size increase with using plugins?
Plugin Version: all, Console & Web: No, Mac: No, Win: Yes, Linux: No. Answer: All plugins used by
your application will be included in the application.
Notes:
If you use no plugins, your application will not change size.
And if you use one class from the plugins, your application size will increase by a few kilobytes.
The documentation of the plugins include a list of all plugin parts and their sizes for the different platforms.
20.0.273
XLS: Custom format string guidelines
Plugin Version: all, Console & Web: No, Mac: Yes, Win: No, Linux: No. Answer: You have to download
the source code and compile a static version of the library.
Notes:
Up to four sections of format codes can be specified. The format codes, separated by semicolons, define the
formats for positive numbers, negative numbers, zero values, and text, in that order. If only two sections
are specified, the first is used for positive numbers and zeros, and the second is used for negative numbers.
If only one section is specified, it is used for all numbers. Four sections example:
639
# ,# # # .00 ); [ Red ] (# ,# # # .00);0.00;”sales ”@
The following table describes the different symbols that are available for use in custom number formats.
Specify colors
To set the text color for a section of the format, type the name of one of the following eight colors in square
brackets in the section. The color code must be the first item in the section.
Instead of using the name of the color, the color index can be used, like this [ Color3 ] for Red. Valid numeric
indexes for color range from 1 to 56, which reference by index to the legacy color palette.
Specify conditions
To set number formats that will be applied only if a number meets a specified condition, enclose the condition in square brackets. The condition consists of a comparison operator and a value. Comparison operators
include: = Equal to; >Greater than; <Less than; >= Greater than or equal to, <= Less than or equal to,
and <>Not equal to. For example, the following format displays numbers that are less than or equal to 100
in a red font and numbers that are greater than 100 in a blue font.
[ Red ] [ <=100 ] ; [ Blue ] [ >100 ]
If the cell value does not meet any of the criteria, then pound signs (”# ”) are displayed across the width of
the cell.
Dates and times
Examples
640
Parameter
x
xLabel
x2Label
value
accValue
totalValue
percent
accPercent
gpercent
dataSet
dataSetName
dataItem
dataGroup
dataGroupName
layerId
fieldN
CHAPTER 20. THE FAQ
Description
The x value of the data point. For an enumerated x-axis (see Axis.setLabels on
what is an enumerated axis), the first data point is 0, and the nth data point
is (n-1).
The bottom x-axis label of the data point.
The top x-axis label of the data point.
The value of the data point.
The sum of values of all data points that are in the same x position and same
data group as the current data point, and with data set number less than
or equal to the current data point. This is useful for stacked charts, such as
stacked bar chart and stacked area chart.
The sum of values of all data points that are in the same x position and same
data group as the current data point. This is useful for stacked charts, such as
stacked bar chart and stacked area chart.
The percentage of the data point based on the total value of all data points
that are in the same x position and same data group as the current data point.
This is useful for stacked charts, such as stacked bar chart and stacked area
chart.
The accumulated percentage of the data point based on the total value of all
data points that are in the same x position and same data group as the current
data point. This is useful for stacked charts, such as stacked bar chart and
stacked area chart.
The percentage of the data point based on the total value of all data points in
a layer.
The data set number to which the data point belongs. The first data set is 0.
The nth data set is (n-1).
The name of the data set to which the data point belongs.
The data point number within the data set. The first data point is 0. The nth
data point is (n-1).
The data group number to which the data point belongs. The first data group
is 0. The nth data group is (n-1).
The name of the data group to which the data point belongs.
The layer number to which the data point belongs. The first layer is 0. The
nth layer is (n-1).
The (N + 1)th extra field. For example, { field0 } means the first extra
field. An extra field is an array of custom elements added using Layer.addExtraField, Layer.addExtraField2, BaseChart.addExtraField or BaseChart.addExtraField2.
641
diFieldN
dsFieldN
dsdiFieldN
Parameter
zx
zy
z
Same as fieldN. See above.
Similar to fieldN, except that dsFieldN means the extra field is indexed by data
set number. The Pth data set corresponds to the Pth element of the extra field.
Similar to fieldN, except that dsdiFieldN means the extra fields are indexed by
both the data set number and data point number. The Pth data item of the
Qth data set corresponds to the Pth element of the (N + Q)th extra field.
Description
The symbol scale in the x dimension. Applicable for layers with symbol scales
set by LineLayer.setSymbolScale.
The symbol scale in the y dimension. Applicable for layers with symbol scales
set by LineLayer.setSymbolScale.
The symbol scale without distinguishing the dimension to use. Applicable for
layers with symbol scales set by LineLayer.setSymbolScale.
Parameter
slope
intercept
corr
stderr
Description
The slope of the trend line.
The y-intercept of the trend line.
The correlation coefficient in linear regression analysis.
The standard error in linear regression analysis.
Parameter
top
bottom
max
min
med
Description
The value of
The value of
The value of
The value of
The value of
Parameter
high
low
open
close
Description
The high value.
The low value.
The open value.
The close value.
Parameter
dir
len
Description
The direction of the vector.
The length of the vector.
the
the
the
the
the
top edge of the box-whisker symbol.
bottom edge of the box-whisker symbol.
maximum mark of the box-whisker symbol.
minimum mark of the box-whisker symbol.
median mark of the box-whisker symbol.
642
CHAPTER 20. THE FAQ
Parameter
radius
value
angle
x
label
xLabel
name
dataSetName
i
dataItem
z
fieldN
diFieldN
dsFieldN
dsdiFieldN
Description
The radial value of the data point.
Same as { radius } . See above.
The angular value of the data point.
Same as { angle } . See above.
The angular label of the data point.
Same as { label } . See above.
The name of the layer to which the data point belongs.
Same as { name } . See above.
The data point number. The first data point is 0. The nth data point is (n-1).
Same as { i } . See above.
The symbol scale. Applicable for layers with symbol scales set by PolarLayer.setSymbolScale.
The (N + 1)th extra field. For example, { field0 } means the first extra
field. An extra field is an array of custom elements added using Layer.addExtraField, Layer.addExtraField2, BaseChart.addExtraField or BaseChart.addExtraField2.
Same as fieldN. See above.
Similar to fieldN, except that dsFieldN means the extra field is indexed by layer
index. The Pth layer corresponds to the Pth element of the extra field.
Similar to fieldN, except that dsdiFieldN means the extra fields are indexed by
both the data set number and data point number. The Pth data item of the
Qth layer corresponds to the Pth element of the (N + Q)th extra field.
Parameter
dir
len
Description
The direction of the vector.
The length of the vector.
Parameter
value
label
Description
The axis value at the tick position.
The axis label at the tick position.
Parameter
[ param ]
[a]
Description
The name of the parameter
If this field a number, it specifies the number of decimal places (digits to the
right of the decimal point).
643
[b]
The thousand separator. Should be a non-alphanumeric character (not 0-9,
A-Z, a-z). Use ’
textasciitilde ’ for no thousand separator. The default is ’
textasciitilde ’, which can be modified using BaseChart.setNumberFormat.
[c]
[d]
textasciitilde ’ for no negative sign character. The default is ’-’, which can be modified using BaseChart.setNumberFormat.
Parameter
yyyy
yyy
yy
y
mmm
mm
m
MMM
MM
M
dd
d
w
hh
h
nn
n
ss
s
a
The decimal point character. The default is ’.’, which can be modified using
BaseChart.setNumberFormat.
The negative sign character. Use ’
Description
The year in 4 digits (e.g. 2002)
The year showing only the least significant 3 digits (e.g. 002 for the year 2002)
The year showing only the least significant 2 digits (e.g. 02 for the year 2002)
The year showing only the least significant 1 digits (e.g. 2 for the year 2002)
The month formatted as its name. The default is to use the first 3 characters
of the english month name (Jan, Feb, Mar ...). The names can be configured
using BaseChart.setMonthNames.
The month formatted as 2 digits from 01 - 12, adding leading zero if necessary.
The month formatted using the minimum number of digits from 1 - 12.
The first 3 characters of the month name converted to upper case. The names
can be configured using BaseChart.setMonthNames.
The first 2 characters of the month name converted to upper case. The names
can be configured using BaseChart.setMonthNames.
The first character of the month name converted to upper case. The names
can be configured using BaseChart.setMonthNames.
The day of month formatted as 2 digits from 01 - 31, adding leading zero if
necessary.
The day of month formatted using the minimum number of digits from 1 - 31.
The name of the day of week. The default is to use the first 3 characters of the
english day of week name (Sun, Mon, Tue ...). The names can be configured
using BaseChart.setWeekDayNames.
The hour of day formatted as 2 digits, adding leading zero if necessary. The 2
digits will be 00 - 23 if the ’a’ option (see below) is not specified, otherwise it
will be 01 - 12.
The hour of day formatted using the minimum number of digits. The digits
will be 0 - 23 if the ’a’ option (see below) is not specified, otherwise it will be
01 - 12.
The minute formatted as 2 digits from 00 - 59, adding leading zero if necessary.
The minute formatted using the minimum number of digits from 00 - 59.
The second formatted as 2 digits from 00 - 59, adding leading zero if necessary.
The second formatted using the minimum number of digits from 00 - 59.
Display either ’am’ or ’pm’, depending on whether the time is in the morning or
afternoon. The text ’am’ and ’pm’ can be modified using BaseChart.setAMPM.
644
CHAPTER 20. THE FAQ
Shape Id
SquareShape
DiamondShape
TriangleShape
RightTriangleShape
LeftTriangleShape
InvertedTriangleShape
CircleShape
StarShape
Value
1
2
3
4
5
6
7
[ Method ]
PolygonShape
[ Method ]
Polygon2Shape
[ Method ]
CrossShape
[ Method ]
Cross2Shape
[ Method ]
langEnglish
langFrench
langGerman
langItalian
langDutch
langSwedish
langSpanish
langDanish
langPortuguese
langNorwegian
langHebrew
langJapanese
langArabic
langFinnish
langGreek
langIcelandic
langMaltese
langTurkish
langCroatian
langTradChinese
langUrdu
langHindi
langThai
langKorean
0
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
Description
Square shape. See (1, 1) above.
Diamond shape. See (2, 1) above.
Triangle shape pointing upwards. See (3, 1) above.
Triangle shape pointing rightwards. See (4, 1) above.
Triangle shape pointing leftwards. See (5, 1) above.
Triangle shape pointing downwards. See (1, 2) above.
Circle shape. See (2, 2) above.
Star shapes of various points. See (2, 3), (2, 4), (2, 5), (3, 1), (3, 2), (3, 3), (3,
4), (3, 5) above for stars with 3 to 10 points.
Polygon shapes symmetrical about a vertical axis with a vertex at the top
center position. See (4, 1), (4, 3), (4, 5), (5, 1) for polygons of 5 to 8 sides.
Polygon shapes symmetrical about a vertical axis but without any vertex at
the top center position. See (4, 2), (4, 4) for polygons of 5 and 6 sides.
’+’ shapes. See (5, 2), (5, 3), (5, 4), (5, 5), (6, 1), (6, 2), (6. 3) for ’+’ shape
with arm width of 0.1 - 0.7.
’X’ shapes. See (6, 4), (6, 5), (7, 1), (7, 2), (7, 3), (7, 4), (7, 5) for ’X’ shapes
with arm width of 0.1 - 0.7.
Roman script
Roman script
Roman script
Roman script
Roman script
Roman script
Roman script
Roman script
Roman script
Roman script
Hebrew script
Japanese script
Arabic script
Roman script
Greek script using smRoman script code
modified smRoman/Icelandic script
Roman script
modified smRoman/Turkish script
modified smRoman/Croatian script
Chinese (Mandarin) in traditional characters
Arabic script
Devanagari script
Thai script
Korean script
645
Nan
1
2
4
8
9
17
33
34
36
37
38
40
42
Meaning
Invalid square root (negative number, usually)
Invalid addition (indeterminate such as infinity + (-infinity))
Invalid division (indeterminate such as 0/0)
Invalid multiplication (indeterminate such as 0*infinity)
Invalid modulo such as (a mod 0)
Try to convert invalid string to a number like val(”x7”)
Invalid argument in a trig function
Invalid argument in an inverse trig function
Invalid argument in a log function
Invalid argument in Pow function
Invalid argument in toolbox financial function
Invalid argument in hyperbolic function
Invalid argument in a gamma function
646
CHAPTER 20. THE FAQ
Symbol
0
#
?
. (period)
%
, (comma)
E- E+ e- e+
$ -+/():space
\
*
(underline)
”text”
@
Description and result
Digit placeholder. For example, if the value 8.9 is to be displayed as 8.90, use
the format # .00
Digit placeholder. This symbol follows the same rules as the 0 symbol. However, the application shall not display extra zeros when the number typed has
fewer digits on either side of the decimal than there are # symbols in the format. For example, if the custom format is # .# # , and 8.9 is in the cell, the
number 8.9 is displayed.
Digit placeholder. This symbol follows the same rules as the 0 symbol. However, the application shall put a space for insignificant zeros on either side of
the decimal point so that decimal points are aligned in the column. For example, the custom format 0.0? aligns the decimal points for the numbers 8.9 and
88.99 in a column.
Decimal point.
Percentage. If the cell contains a number between 0 and 1, and the custom
format 0% is used, the application shall multiply the number by 100 and adds
the percentage symbol in the cell.
Thousands separator. The application shall separate thousands by commas if
the format contains a comma that is enclosed by number signs (# ) or by zeros.
A comma that follows a placeholder scales the number by one thousand. For
example, if the format is # .0,, and the cell value is 12,200,000 then the number
12.2 is displayed.
Scientific format. The application shall display a number to the right of the
”E” symbol that corresponds to the number of places that the decimal point
was moved. For example, if the format is 0.00E+00, and the value 12,200,000
is in the cell, the number 1.22E+07 is displayed. If the number format is #
0.0E+0, then the number 12.2E+6 is displayed.
Displays the symbol. If it is desired to display a character that differs from one
of these symbols, precede the character with a backslash (\). Alternatively,
enclose the character in quotation marks. For example, if the number format
is (000), and the value 12 is in the cell, the number (012) is displayed.
Display the next character in the format. The application shall not display the
backslash. For example, if the number format is 0\!, and the value 3 is in the
cell, the value 3! is displayed.
Repeat the next character in the format enough times to fill the column to its
current width. There shall not be more than one asterisk in one section of the
format. If more than one asterisk appears in one section of the format, all but
the last asterisk shall be ignored. For example, if the number format is 0*x,
and the value 3 is in the cell, the value 3xxxxxx is displayed. The number
of x characters that are displayed in the cell varies based on the width of the
column.
Skip the width of the next character. This is useful for lining up negative and
positive values in different cells of the same column. For example, the number
format (0.0 );(0.0) aligns the numbers 2.3 and -4.5 in the column even though
the negative number is enclosed by parentheses.
Display whatever text is inside the quotation marks. For example, the format
0.00 ”dollars” displays 1.23 dollars when the value 1.23 is in the cell.
Text placeholder. If text is typed in the cell, the text from the cell is placed
in the format where the at symbol (@) appears. For example, if the number
format is ”Bob ”@” Smith” (including quotation marks), and the value ”John”
is in the cell, the value Bob John Smith is displayed.
647
[ Black ]
[ Green ]
To display
Months
Months
Months
Months
Months
Days
Days
Days
Days
Years
Years
Hours
Hours
Minutes
Minutes
Seconds
Seconds
Time
Time
Time
Time
Elapsed time
Elapsed time
Elapsed time
To display
1234.59
8.9
.631
12
1234.568
44.398
102.65
2.8
5.25
5.3
12000
12000
12400000
[ White ]
[ Blue ]
[ Magenta ]
As
1-12
01-12
Jan-Dec
January-December
J-D
1-31
01-31
Sun-Sat
Sunday-Saturday
00-99
1900-9999
0-23
00-23
0-59
00-59
0-59
00-59
4 AM
4:36 PM
4:36:03 P
4:36:03.75
1:02
62:16
3735.80
As
1234.6
8.900
0.6
12.0
1234.57
44.398
102.65
2.8
5 1/4
5 3/10
12,000
12
12.4
[ Yellow ]
[ Cyan ]
Use this code
m
mm
mmm
mmmm
mmmmm
d
dd
ddd
dddd
yy
yyyy
h
hh
m
mm
s
ss
h AM/PM
h:mm AM/PM
h:mm:ss A/P
h:mm:ss.00
[ h ] :mm
[ mm ] :ss
[ ss ] .00
Use this code
# # # # .#
# .000
0.#
# .0#
# .0#
???.???
???.???
???.???
# ??/??
# ??/??
# ,# # #
#,
0.0,,
[ Red ]
Was this manual useful for you? yes no
Thank you for your participation!

* Your assessment is very important for improving the work of artificial intelligence, which forms the content of this project

Download PDF

advertisement