The Unofficial RB-NUG FAQ

maintained by Chris Cummer
              chris@postal-code.com
              http://www.postal-code.com/public/rbnugfaq.txt
              
Last updated: 06/02/2002
       Issue: 015
       

----------------------------------------------------------------------------------------------------------------
NOTE: 2008-03-28
At this point this document is so hopelessly out of date as to be considered archaeological in nature. Future 
civilizations will no doubt find it fascinating.
----------------------------------------------------------------------------------------------------------------

----------------------------------------------------------------------------------------------------------------
NOTE: 2005-12-12
Obviously I no longer maintain this FAQ, as it hasn't been updated in three years. I no longer use REALbasic and 
haven't kept up to date with the development of it. You might consider this to now be an historical artifact in the 
history of REALbasic, kept here for posterity.
----------------------------------------------------------------------------------------------------------------


       
New in this vers: 5.1 updated, 5.5 added

Please send any relevant code examples, spelling corrections, FAQ suggestions and question/answer rewording to the address above rather than polluting the list. Cheers!
For more information about REALbasic: http://www.realbasic.com


0.0 QUESTION INDEX

Miscellany
    1.1 Is there a searchable archive of this newsgroup?
    1.2 Is there an etiquette for posting to the RB NUG?
    1.3 Who is this guy Matt Neuburg and why does he answer in page numbers?
    1.4 I just launched REALbasic and received a warning that another copy of REALbasic is already running with my serial number. Then it quits and I must re-enter my serial numer. What's going on?
    1.5 What is the correct capitalization/spelling of <insert word here>?
       
General Programming
    2.1 How do I get the cube root?
    2.2 Is MouseUp is broken in <insert control name herecontrol?
    2.3 I get a stack overflow error when I try to call up to the parent's EnableMenuItems event in my control subclass. What's going wrong?
    2.4 My menubars appear disabled until I click on them. Then they appear enabled, as they should. How can I make the menus refresh themselves?
    2.5 Why won't ImageWells and Bevel buttons accept the image I'm trying to put into them?
    2.6 How do I create a constructor/destructor method in my custom class?
        
Classic
    3.1 When I run my application in Classic I have two Apple menus showing, one with an About box, one without. Huh?
        
OS X
    4.1 How do I enable the Preferences menu under the Application menu?
    4.2 How do I use the Preferences menu under the Application menu?
    4.3 How do I use sheets in my application?
    4.4 How do I add an OS X application icon to my app?
    4.5 How do I execute a command via the command line from REALbasic as root?
    4.6 How do I use drawers in my application?
    
Resources
    5.1 Carbon Declare Library
    5.2 Einhugur Programming Resources
    5.3 Alfred Van Hoek's REALbasic Plugins
    5.4 httpSocket
    5.5 Carbon Events Plugin


1.0 MISCELLANY

1.1 Q: Is there a searchable archive of this newsgroup?
    A: Yes. Chris Little writes:
    "The most comprehensive archives are at:

    	http://dbserver.realsoftware.com/KBDB/search.php
        http://realbasic.zapkerpow.com/
   
1.2 Q: Is there an etiquette for posting to the RB NUG?
    A: Yes there is, as Lorin Rivers points out:
    "The purpose of the NUG is discussion of use of REALbasic. Off-topic posts are strongly discouraged."
    
    Frank Bitterlich also mentions there are some general rules you might follow to make life easier for everyone else on the list:
    
    1. "Send messages to the NUG in plain-text emails only. HTML posts are frowned upon for three reasons: HTML messages are completely unreadable on the digest; some email clients cannot process HTML emails; and they increase the list volume unnecessary."   
    2. "If you invoke an email auto-reply system on you mail account before going on vacation, UNSUBSCRIBE from the list. It's no fun to watch the list getting flooded with "I'm on vacation..." emails from your account as you receive list email."
    3. And I would add: keep in mind that the programming skills and experience of the members on this list vary greatly, from those with decades of of experience to those with literally none. Questions are bound to reflect the skill level of the poster; be nice and try to couch your responses accordingly.
    
    And the "Unofficial REALbasic NUG List Netiquette FAQ", maintained by Peter Job, is an excellent resource on exactly what the title says.Check it out at:
    
    	http://www.ziggy.speedhost.com/rbnugfaq.html

1.3 Q: Who is this guy Matt Neuburg and why does he answer in page numbers?
    A: Matt is the author of the seminal O'Reilly book "REALbasic: The Definitive Guide" (currently in 2nd edition). When he answers in page numbers he's referencing the contents of his book. Unpaid plug: you owe it to yourself to check this book out.
        
1.4 Q: I just launched REALbasic and received a warning that another copy of REALbasic is already running with my serial number. Then it quits and I must re-enter my serial numer. What's going on?
    A: Sometimes when REALbasic crashes and you restart it it will launch with the message given above because of the copy protection scheme it implements (assuming you actually aren't really  using a duplicate serial number on the same network). Restarting  your computer should fix the problem.

    Lorin Rivers also notes that:
    "Turning off AppleTalk, then on again will also clear this problem."
    
1.5 Q: What is the correct capitalization/spelling of <insert word here>?
    A: REALbasic
       REAL Software
       Mac OS X



2.0 GENERAL PROGRAMMING

2.1 Q: How do I get the cube root?
    A: pow(x, 1/3)
    
2.2 Q: Is MouseUp is broken in <insert control name herecontrol? I have code in the MouseUp event of my control but nothing happenswhen I click on it.
    A: No, you just need to first handle the MouseDown event. As 
    Charles Yeomans writes:
    "You need to return TRUE from the MouseDown event, otherwise the MouseUp event does not occur."
    
2.3 Q: I have a subclass of a control. I've created a new event called EnableMenuItems so that I can execute the parent class's EnableMenuItems event as well as the subclass's. When I try to call it I get a stack overflow error. What's wrong?
    A: In the EnableMenuItems event handler of your subclass you need to call the parent class's EnableMenuItems event handler using:
    
    	EnableMenuItems()
    	
    Note the parenthesis on the end. Otherwise the subclass's EnableMenuItems is calling itself recursively. (Thanks to Charles Yeomans).
    
2.4 Q: My menubars appear disabled until I click on them. Then they appear enabled, as they should. How can I make the menus refresh themselves?
    A: Use the EnableMenuItems global method to force a menu refresh.
    
2.5 Q: Why won't ImageWells and Bevel buttons accept the image I'm trying to put into them?
    A: Mike Benonis writes:
    "ImageWells only like PICT images and not other formats. I wrote this method to work around this issue:
    
    Sub DisplayImageInImageWell( Image As Picture, IW As ImageWell )
        Dim F As FolderItem
        F=TemporaryFolder.Child("ImageWellConversion.temp")
        F.SaveAsPicture Image
        IW.Image=TemporaryFolder.Child("ImageWellConversion.temp").OpenAsPicture
        F.Delete
    End Sub

    Pass the image you want displayed (it can be any image, even one createdwith NewPicture) and the ImageWell you want to display it in, and thismethod displays the image.

    Here is a modified version to display images that a BevelButton doesn't like (especially images created with NewPicture):

    Sub DisplayImageInBevelButton(Image As Picture, B As BevelButton)
        Dim F As FolderItem
        F=TemporaryFolder.Child("BevelButtonConvert.temp")
        F.SaveAsPicture Image
        B.Icon=TemporaryFolder.Child("BevelButtonConvert.temp").OpenAsPicture
        F.Delete
    End Sub
    
2.6 Q: How do I create a constructor/destructor method in my custom class?
    A: For a constructor create a method the same name as the class. For a destructor prepend a ~ (tilde).
       Example: For class MyCustomClass create the following methods in your class:
       
           constructor: MyCustomClass()
           destructor:  ~MyCustomClass()



3.0 CLASSIC

3.1 Q: When I run my application in Classic I have two Apple menus showing, one with an About box, one without. Huh?
    A: Noah Desch writes:"You have somewhere declared a call to CarbonLib. In a classic app, this forces CarbonLib to load in addition to InterfaceLib, causing a second apple menu to appear. Change the carbon declare to its classic counterpart and you will be fine."
    
    Which is to say: if you use Carbon declares, don't compile your application for PPC.



4.0 OS X

4.1 Q: How do I enable the Preferences menu under the Application menu?
    A: Via the following method:

    Sub SetCarbonPrefsMenu( pBool as Boolean ) 
        #If TargetCarbon then
          Declare Sub EnableMenuCommand Lib "CarbonLib" (inMenu as Integer, inCommandID as OSType)
          Declare Sub DisableMenuCommand Lib "CarbonLib" (inMenu As Integer, inCommandID As OSType)
          
          If pBool Then
            EnableMenuCommand 0,"pref"
          Else
            DisableMenuCommand 0, "pref"
          End If
  
        #Endif
    End Sub
        
4.2 Q: How do I use the Preferences menu under the Application menu?
    A: The Preferences menu sends an Apple event to your application when it has been selected. To handle this appleevent, place the following code in the HandleAppleEvent event of your Application class (you do have a class extending Application, don't you?)
    
    #If TargetCarbon then
        // Handle the call from the Carbon preferences menu
        If eventClass = "aevt" and eventID = "pref" then
            // Do you prefs handling code here, such as...
            PrefsWindow.show
    
            return true
        End if
    #Endif

4.3 Q: How do I use sheets in my application?
    A: Matthew Williams writes:
    "Set your sheet (dialog) to MacProcID 1088 and window type to Document.  Then call the following code, which you can store in a global module:

    Sub ShowSheet(sheet as window, parent as window)
        Dim i as integer
        
        #If TargetCarbon then
        Declare Function ShowSheetWindow Lib "CarbonLib" (sheet As WindowPtr, Parent as WindowPtr) As Short
    
        i = ShowSheetWindow(sheet,parent)
        #endif
    
        sheet.showmodal
    End Sub
    
    Mike Benonis writes:
    "One more thing.  In your sheet's open event, call this function:

    Declare Function SetThemeWindowBackground Lib "CarbonLib" ( inWindow As WindowPtr, inBrush As Integer, inUpdate As Boolean) As Integer

    Dim Err As Integer
    Err=SetThemeWindowBackground(Self, 53, True)
    If Err<>0 Then
        MsgBox "SetThemeWindowBackground failed; err="+Str(Err)
    End If

    This will make your sheet transparent."
    
4.4 Q: How do I add an OS X application icon to my app?
    A: Noah Desch writes:
    "IconPaste and the RB build dialog don't support OSX icons. You'll need to put the OSX icon resources into a resource file (with ID 128) which you then drag into your project window. This will cause the icon resources to be compiled into your application.

    The only resource needed for OSX icons is the 'icns' resource, but you'll probably want to include all the others as well in case someone tries to use your program under OS 9."
    
    Erick Tejkowski (author of "REALbasic for Dummies") has a tutorial for adding OS X icons at: 
    
        http://www.ResExcellence.com/realbasic/12-13-01.shtml

4.5 Q: How do I execute a command via the command line from REALbasic as root?
    A: Joe Strout wrote:
    The correct solution to this problem (which seems to come up here every few days!) is:

        s.execute "echo " + password + " | sudo -S someCommandGoesHere"

    [Where s is an instance of shell - ed.]

    Note that I'm using sudo here instead of su; this is both because su is dangerous and not recommended by Apple, and because sudo has a "-S" option which tells it to get the password from stdin, which su does not have (as far as I can tell).

    To get the password into stdin, we feed it to echo, which echoes it right back, and pipe the output of that to the input of sudo.

4.6 Q: How can I use drawers in my application?
    A: Currently you cannot. REALbasic compiles Carbon-based applications and drawers are a Cocoa-only feature.
    
    

5.0 RESOURCES

5.1 Carbon Declare Library (free)
    An incredibly useful module full of Carbon Declares that give you direct access to many OS X features not directly supported by REALbasic (including enabling and modifying the Preferences menu).
    
        http://kevin.sb.org/TMBS/Index.shtml 

5.2 Einhugur Programming Resources
    A subscription-based service prodiving numerous REALbasic plugins.
    
        http://www.einhugur.com/
        
5.3 Alfred Van Hoek's REALbasic Plugins
    Notably: MovieWorks plugin, NavDialog plugin, HTMLrendering plugin
    
        http://homepage.mac.com/vanhoek/
        
5.4 httpSocket
    The easiest way to handle incoming and outgoing http data. Created by Dan Vanderkam
    
        http://www.nd.edu/~jvanderk/rb/ 
        
5.5 Carbon Events plugin
    Adds numerous useful Carbon-enabled properties, events and functions to your application. Commercial.
    
        http://www.everydaysoftware.net