About Clue:
The most comprehensive open-source BeOS GUI/API/Object tracing tool,
allowing inspection on almost all of the BeOS native objects, 309 in
all right now! Clue is analogous to printf, for BeOS programmers. Clue
allows you to easily view printf-like statements from several apps.
Clue separates the messages from different apps (even different
instances of the same app) into a clean, easy to view wi
Update July 6, 2004: I have now open-sourced my code through www.beunited.org. If you want to help develop Clue, please feel free to work on the project!
September 16, 2002: In
April of this year, I had decided to stop developing Clue even though I
hadn't implemented everything I had originally set out to do. That's
now changed. I've decided that I need to follow through with the
project and see it come to the end that I expected. So right now I'm
working on making Clue the most comprehensive BeOS object tracing tool
there is or possibly ever will be. This means adding nearly ALL of the
BeOS classes, enums, and structs! TRACE_OBJECT already covers 85
classes, enums, and structs in the current version, but that number
will probably at least double in the next version. Most of the code is
going into the sender, but I'm also implementing code in the viewer to
enable object by object and method by method selection of what
Fingerprints the clients send. This will allow very granular tracing of
only the objects and methods you care about, as well as saving CPU
cycles by not having to trace base classes or methods on objects you
don't care about. It's a lot of coding, and I'm afraid that I won't be
able to test it very well as there are too many classes, enums, and
structs to cover them all by myself. So I'll have to rely on BeOS
developer community to help me test. I don't have a specific time frame
right now, but I'm guessing it will be within a month or two. I'm
also looking to release it in multiple languages. So I'm looking for
people to help with string translations for Spanish and Swedish, as
well as update some of the other languages (like German) that have
mostly been translated already but new string were added since then. If you can help, please contact me at 'yobkadon@hotmail.com'. Thanks, Jeff Braun
You might want to use the 2001.5.16 Beta2 if you have problems with this one as it's in heavy development stage.
I will be releasing updated versions quite frequently as I
begin to fill out the inspection functions for all of the new objects.
There's a good chance something might break, if so, I'm counting on you
to let me know what those problems are. Again, this is a development
release, there are several documentation and UI issues that will be
addressed in later releases. So please email me or at least leave a talkback comment to let me know what you think.
You can start Clue at any time, it doesn't
have to be started before you run your app. It's efficient in that the
client app only sends data that matches the Event selection filter in
Clue. The second you change your filter in Clue, it's applied
immediately to all client apps.
The Clue trace statements are as minimal as possible and
follow the printf format you already know. There are four different
calls you can make: TRACE_CLASS, TRACE_METHOD, TRACE_OBJECT, and
TRACE_SIMPLE. Here is an example:
TRACE_SIMPLE ((CC_APPLICATION, CR_INFO, "some number = %i", number));
With this small statement, the following items will be sent to Clue:
- what Category it belongs to
- what Event in that Category it belongs to
- the class method name
- the class name
- the file name that the class exists in
- the line number that generated the message
- the thread id
- an application-wide, unique sequence number
- the date it was sent
- the exact time it was sent
- some programmer description for the event
- and optionally (for TRACE_OBJECT only), detail data
The TRACE_OBJECT macro is like PrintToStream on steroids, but it is
much more than that. TRACE_OBJECT allows for Inspection on many BeOS
classes that don't have a PrintToStream function, or items that can't
have a PrintToStream function like enums.
Included in the zip download is a sample application that
shows how to easily program for Clue. Also included is extensive,
graphical documentation on how to use and program for Clue.
Clue now exists in six different laguages: English, German,
French, Russian, Portuguese, and Czech, with Spanish and Swedish coming
soon. If I missed your language, there is an included file that you
need to translate into your language, send it to me, and I will build
your localized version.
What's coming in future releases?
- printing capability (getting there)
- ability to edit more properties and settings
- better scripting support
- replacing the Be supplied BListView as it's too slow
- more Cut/Copy/Paste functionality
Key Features:
- Multiple Windows (you can export and reopen saved files)
- Total customization of the colors Clue uses
- Most settings are saved to your disk
- Drag-n-Drop support to the desktop, and other applications.
- Clipboard support (copying data to)
- TRACE_METHOD allows for some simple performance timing (how long the method took to execute)
- Inspection of over 85 BeOS classes, enums, and structs, with more to come! See the list below.
There are currently 309 traceable BeOS
objects that you can use with TRACE_OBJECT. Here are the current list
of those objects (the ones in bold aren't fully implemented in this
release):
77 Enums: alignment,
alpha_function,
border_style,
B_TRANSLATION_ERROR,
buffer_layout,
buffer_orientation,
button_width,
cap_mode,
color_control_layout,
color_space,
cpu_type,
data_bits,
data_rate,
directory_which,
direct_buffer_state,
direct_driver_state,
drawing_mode,
file_panel_mode,
file_panel_button,
filter_result,
font_direction,
font_file_format,
font_metric_mode,
gs_attributes,
hash_mark_location,
icon_size,
image_type,
info_location,
input_device_notification,
input_device_type,
input_method_op,
interpolation_mode,
join_mode,
list_view_type,
mail_flags,
media_display_flags,
media_file_accept_format_flags,
media_flags,
media_format_family,
media_format_flags,
media_frame_flags,
media_multi_channels,
media_multi_matrix,
media_parameter_flags,
media_producer_status,
media_realtime_flags,
media_seek_type,
media_type,
menu_bar_border,
menu_layout,
message_delivery,
message_source,
midi_axe,
mpeg_id,
node_flavor,
node_kind,
orientation,
parity_mode,
query_op,
reverb_mode,
source_alpha,
stop_bits,
swap_action,
status_t,
synth_mode
tab_position,
thread_state,
thumb_style,
timecode_type,
undo_state,
value_kind,
version_kind,
video_orientation,
window_alignment,
window_feel,
window_look,
and window_type.
135 Classes:
BAlert,
BAppFileInfo,
BApplication,
BAutolock,
BBitmap,
BBitmapStream,
BBox,
BBuffer,
BBufferConsumer,
BBufferGroup,
BBufferIO,
BBufferProducer
BButton,
BChannelControl,
BChannelSlider,
BCheckBox,
BClipboard,
BColorControl,
BContinuousParameter,
BControl,
BControllable,
BDirectory,
BDirectWindow,
BDiscreteParameter,
BDragger,
BEntry,
BEntryList,
BFile,
BFileGameSound,
BFileInterface,
BFilePanel,
BFlattenable,
BFont,
BGameSound,
BGLView,
BHandler,
BInputDevice,
BInvoker,
BJoystick,
BList,
BListItem,
BListView,
BLocker,
BLooper,
BMediaAddOn,
BMediaDecoder,
BMediaEncoder,
BMediaEventLooper,
BMediaFile,
BMediaFiles,
BMediaFormats,
BMediaNode,
BMediaRoster,
BMediaTheme,
BMediaTrack,
BMenu,
BMenuBar,
BMenuField,
BMenuItem,
BMessage,
BMessageFilter,
BMessageQueue,
BMessageRunner,
BMessenger,
BMidi,
BMidiPort,
BMidiStore,
BMidiSynth,
BMidiSynthFile,
BMidiText,
BMimeType,
BMultiChannelControl,
BNode,
BNodeInfo,
BNullParameter,
BOptionControl,
BOptionPopUp,
BOutlineListView,
BParameter,
BParameterGroup,
BParameterWeb,
BPath,
BPicture,
BPictureButton,
BPoint,
BPolygon,
BPopUpMenu,
BPrintJob,
BPropertyInfo,
BPushGameSound,
BQuery,
BRadioButton,
BRect,
BRegion,
BResources,
BResourceStrings,
BRoster,
BSamples,
BScreen,
BScrollBar,
BScrollView,
BSeparatorItem,
BSerialPort,
BShape,
BShelf,
BSimpleGameSound,
BSlider,
BSmallBuffer,
BSound,
BSoundFile,
BSoundPlayer,
BStatable,
BStatusBar,
BStopWatch,
BStreamingGameSound,
BString,
BStringItem,
BStringView,
BSymLink,
BSynth,
BTab,
BTabView,
BTextControl,
BTextView,
BTimeCode,
BTimedEventQueue,
BTimeSource,
BTranslator,
BTranslatorRoster,
BView,
BVolume,
BVolumeRoster,
BWindow.
media_node,
unicode_block
97 Structs:
alert_type,
app_info,
area_info,
buffer_clone_info,
button_spacing,
clipping_rect,
color_map,
compound_type,
cpu_info,
direct_buffer_info,
dormant_flavor_info,
dormant_node_info,
edge_info,
encode_parameters,
entry_ref,
escapement_delta,
flavor_info,
font_height,
gs_attribute,
gs_attribute_info,
gs_audio_format,
GUID,
image_info,
key_info,
key_map,
live_node_info,
media_aiff_description,
media_asf_description,
media_audio_header,
media_avi_description,
media_avr_description,
media_beos_description,
media_codec_info,
media_decode_info,
media_destination,
media_encode_info,
media_encoded_audio_format,
media_encoded_audio_header,
media_encoded_video_format,
media_encoded_video_header,
media_file_format,
media_file_format_id,
media_format,
media_format_description,
media_header,
media_header_time_code,
media_input,
media_misc_description,
media_mpeg_description,
media_multi_audio_info,
media_multistream_format,
media_multistream_header,
media_node_attribute,
media_output,
media_quicktime_description,
media_raw_audio_format,
media_raw_video_format,
media_request_info,
media_seek_tag,
media_source,
media_timed_event,
media_video_display_info,
media_video_header,
media_wav_description,
mail_notification,
mail_pop_account,
mouse_map,
node_ref,
overlay_rect_limits,
overlay_restrictions,
pattern,
platform_type,
port_info,
property_info,
rgb_color,
screen_id,
scroll_bar_info,
sem_info,
system_info,
team_info,
team_usage_info,
text_run,
text_run_array,
thread_info
timecode_info,
translation_format,
TranslatorBitmap,
translator_info,
TranslatorGroups,
TranslatorSound,
TranslatorStyledTextRecordHeader,
TranslatorStyledTextStreamHeader,
TranslatorStyledTextTextHeader,
TranslatorStyledTextStyleHeader,
tuned_font_info,
value_info,
version_info,
The online documentation can be found here.
Here is an example of all of the information you can view from
passing a BDirectory and a BBox pointer to just two TRACE_OBJECT calls:
**** Example of a BBox inspection:
Inspecting a BBox:
[BBox object, ptr=0x80025b90]
| Border: [border_style enum, 0x00000001] B_FANCY_BORDER
| Label= Inspectable controls:
| LabelView= NULL
|
+ BBox baseclass [BView object, ptr=0x80025b90]
| Bounds: [BRect object, ptr=0xfd041e0c]
| | Left= 0.00
| | Top= 0.00
| | Right= 240.00
| | Bottom= 272.00
| | IsValid= True
| | Width= 240.00
| | IntegerWidth= 240
| | Height= 272.00
| | IntegerHeight= 272
| CountChildren= 5
| Heirerarchy of BViews:
| | [1] surrounding bbox (ptr=0x80025b90, has 5 children)
| | | [1] btnGenerate 101 (ptr=0x80025d40, has 0 children)
| | | [2] btnInspect (ptr=0x80025f30, has 0 children)
| | | [3] chkTimer (ptr=0x80026110, has 0 children)
| | | [4] rdoButton (ptr=0x800262e0, has 0 children)
| | | [5] scroll view for txtEntry (ptr=0x800271c0, has 2 children)
| | | | [1] txtEntry (ptr=0x800264c0, has 0 children)
| | | | [2] _VSB_ (ptr=0x80027358, has 0 children)
| DrawingMode: [drawing_mode enum, 0000000000] B_OP_COPY
| EventMask= [0]
| Flags= [738197504], B_WILL_DRAW, B_NAVIGABLE_JUMP, B_FRAME_EVENTS
| Frame: [BRect object, ptr=0xfd041e0c]
| | Left= 5.00
| | Top= 5.00
| | Right= 245.00
| | Bottom= 277.00
| | IsValid= True
| | Width= 240.00
| | IntegerWidth= 240
| | Height= 272.00
| | IntegerHeight= 272
| GetFont: [BFont object, ptr=0xfd041e24]
| | ascent= 10.59
| | descent= 2.59
| | leading= 0.00
| | Blocks: [unicode_block object, ptr=0xfd041cec]
| | | B_BASIC_LATIN_BLOCK
| | | B_LATIN1_SUPPLEMENT_BLOCK
| | | B_LATIN_EXTENDED_A_BLOCK
| | | B_LATIN_EXTENDED_B_BLOCK
| | | B_SPACING_MODIFIER_LETTERS_BLOCK
| | | B_BASIC_GREEK_BLOCK
| | | B_GENERAL_PUNCTUATION_BLOCK
| | | B_CURRENCY_SYMBOLS_BLOCK
| | | B_LETTERLIKE_SYMBOLS_BLOCK
| | | B_MATHEMATICAL_OPERATORS_BLOCK
| | | B_GEOMETRIC_SHAPES_BLOCK
| | | B_PRIVATE_USE_AREA_BLOCK
| | | B_SPECIALS_BLOCK
| | BoundingBox: [BRect object, ptr=0xfd041cdc]
| | | Left= -0.17
| | | Top= -0.24
| | | Right= 1.25
| | | Bottom= 0.96
| | | IsValid= True
| | | Width= 1.42
| | | IntegerWidth= 2
| | | Height= 1.20
| | | IntegerHeight= 2
| | Direction: [font_direction enum, 0000000000] B_FONT_LEFT_TO_RIGHT
| | IsFixed= False
| | IsFullAndHalfFixed= False
| | Face= [32], B_BOLD_FACE
| | FileFormat: [font_file_format enum, 0000000000] B_TRUETYPE_WINDOWS
| | Family= Swis721 BT
| | Style= Bold
| | Flags= [0]
| | Rotation= 0.00
| | Shear= 90.00°
| | Size= 11.00
| | Spacing= [2], B_BITMAP_SPACING
| | Encoding= [0], B_UNICODE_UTF8 (UTF-8)
| GetPreferredSize: width= 240.00, height= 272.00
| HighColor: [rgb_color struct, ptr=0xfd041dec]
| | red= 0
| | green= 0
| | blue= 0
| | alpha= 255
| LowColor: [rgb_color struct, ptr=0xfd041dec]
| | red= 255
| | green= 128
| | blue= 128
| | alpha= 255
| ViewColor: [rgb_color struct, ptr=0xfd041dec]
| | red= 255
| | green= 128
| | blue= 128
| | alpha= 255
| IsFocus: False
| IsHidden: False
| IsPrinting: False
| LineCapMode: [cap_mode enum, 0x00000003] B_BUTT_CAP
| LineJoinMode: [join_mode enum, 0x00000002] B_BEVEL_JOIN
| Parent= The CView
| PenLocation: [BPoint object, ptr=0xfd041e1c]
| | X= 0.00
| | Y= 0.00
| Origin: [BPoint object, ptr=0xfd041e1c]
| | X= 0.00
| | Y= 0.00
|
+ BView baseclass [BHandler object, ptr=0x80025b90]
| Name= surrounding bbox
| GetSupportedSuites: [BMessage object, ptr=0xfd041d50]
| | B_MESSAGE_TYPE, (), [1 of 1], what=
| | | B_STRING_TYPE, (suites), [1 of 2], size=18, suite/vnd.Be-view
| | | B_STRING_TYPE, (suites), [2 of 2], size=21, suite/vnd.Be-handler
| | | B_PROPERTY_INFO_TYPE, (messages), [1 of 2], size=172
| | | 0x000000: 00,04,00,00,00,01,00,00,00,46,72,61,6d,65,00,00, |.........Frame..|
| | | 0x000010: 00,00,00,00,54,45,47,50,54,45,53,50,00,00,00,00, |....TEGPTESP....|
| | | 0x000020: 01,00,00,00,00,00,00,00,48,69,64,64,65,6e,00,00, |........Hidden..|
| | | 0x000030: 00,00,00,00,54,45,47,50,54,45,53,50,00,00,00,00, |....TEGPTESP....|
| | | 0x000040: 01,00,00,00,00,00,00,00,56,69,65,77,00,00,00,00, |........View....|
| | | 0x000050: 00,00,54,4e,43,50,00,00,00,00,01,00,00,00,00,00, |..TNCP..........|
| | | 0x000060: 00,00,56,69,65,77,00,00,00,00,00,00,00,00,00,00, |..View..........|
| | | 0x000070: 02,00,00,00,03,00,00,00,06,00,00,00,00,00,00,00, |................|
| | | 0x000080: 54,43,45,52,00,00,00,00,00,00,00,00,4c,4f,4f,42, |TCER........LOOB|
| | | 0x000090: 00,00,00,00,00,00,00,00,47,4e,4f,4c,00,00,00,00, |........GNOL....|
| | | 0x0000a0: 00,00,00,00,00,00,00,00,00,00,00,00 |............ |
| | | B_PROPERTY_INFO_TYPE, (messages), [2 of 2], size=166
| | | 0x000000: 00,03,00,00,00,01,00,00,00,53,75,69,74,65,73,00, |.........Suites.|
| | | 0x000010: 00,00,00,00,00,54,45,47,50,00,00,00,00,01,00,00, |.....TEGP.......|
| | | 0x000020: 00,00,00,00,00,4d,65,73,73,65,6e,67,65,72,00,00, |.....Messenger..|
| | | 0x000030: 00,00,00,00,54,45,47,50,00,00,00,00,01,00,00,00, |....TEGP........|
| | | 0x000040: 00,00,00,00,49,6e,74,65,72,6e,61,6c,4e,61,6d,65, |....InternalName|
| | | 0x000050: 00,00,00,00,00,00,54,45,47,50,00,00,00,00,01,00, |......TEGP......|
| | | 0x000060: 00,00,00,00,00,00,00,00,00,00,73,75,69,74,65,73, |..........suites|
| | | 0x000070: 00,52,54,53,43,00,00,00,00,6d,65,73,73,61,67,65, |.RTSC....message|
| | | 0x000080: 73,00,44,54,43,53,00,00,00,00,00,00,00,00,47,4e, |s.DTCS........GN|
| | | 0x000090: 53,4d,00,00,00,00,00,00,00,00,52,54,53,43,00,00, |SM........RTSC..|
| | | 0x0000a0: 00,00,00,00,00,00 |...... |
**** Example of a BDirectory inspection:
Inspecting a BDirectory:
[BDirectory object, ptr=0xfd0420a8]
| InitCheck= B_OK
| CountEntries= 13
| IsRootDirectory= False
|
+ BDirectory baseclass [BNode object, ptr=0xfd0420a8]
| InitCheck= B_OK
| GetNextAttrName list:
| | name= _trk/windframe
| | name= _trk/windwkspc
| | name= _trk/columns_le
| | name= _trk/viewstate_le
| | name= _trk/pinfo_le
|
+ BNode baseclass [BStatable object, ptr=0xfd0420a8]
| GetCreationTime= 954093930
| GetModificationTime= 981565529
| GetAccessTime= 990535722
| GetOwner= 0
| GetGroup= 0
| GetPermissions: [mode_t flag, 0x010041ed] S_IRUSR, S_IWUSR, S_IXUSR, S_IRGRP, S_IXGRP, S_IROTH, S_IXOTH
| GetSize= 2048
| IsFile= False
| IsDirectory= True
| IsSymLink= False
|
+ BDirectory baseclass [BEntryList object, ptr=0xfd0420d8]
| CountEntries= 13
|